@agentix-security/nextjs 0.1.11 → 0.1.12

package/dist/index.cjs

@@ -459,6 +459,30 @@ function auditRow(sdk, req, route, status, fp, fields) {
     ...fields
   };
 }
+function buildTools(sdk, baseUrl) {
+  const registry = sdk.getIntentRegistry();
+  const descriptions = sdk.config.descriptions ?? {};
+  return Object.fromEntries(
+    [...registry.entries()].map(([intent, entry]) => {
+      const tool = {
+        routes: [...entry.routes],
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+      };
+      if (descriptions[intent]) tool.description = descriptions[intent];
+      return [intent, tool];
+    })
+  );
+}
+function agentInstructions(ttlSec) {
+  return [
+    "1. Pick the tool below that matches what you need to do.",
+    `2. Fetch the tool's token_url with a GET request (no body, no auth required). You will receive JSON containing an access_token. Tokens are valid for ${ttlSec} seconds.`,
+    '3. Include the token in the Authorization header on every API request: "Authorization: Bearer <access_token>"',
+    "4. If you receive HTTP 401 (missing_token or invalid_token), your token is missing or expired \u2014 fetch a new one from the same token_url.",
+    "5. If you receive HTTP 403 (out_of_scope), your token's intent does not cover this route. Get a new token from the token_url of the correct tool.",
+    "6. Each token is scoped to exactly one intent. Use a different token for each capability."
+  ];
+}
 function agentixMiddleware(sdk) {
   return async (req) => {
     await sdk.ensureInitialized();
@@ -468,14 +492,8 @@ function agentixMiddleware(sdk) {
     const cp = (sdk.config.controlPlaneUrl ?? "https://agentix-control-plane.onrender.com").replace(/\/$/, "");
     const licenseKey = sdk.config.licenseKey;
     const tokenSecret = sdk.getResolvedTokenSecret();
+    const ttlSec = Math.floor((sdk.config.tokenTtlMs ?? 15 * 60 * 1e3) / 1e3);
     if (req.method === "GET" && pathname === "/.well-known/ai-agent.json") {
-      const registry = sdk.getIntentRegistry();
-      const tools = Object.fromEntries(
-        [...registry.entries()].map(([intent, entry]) => [
-          intent,
-          { routes: [...entry.routes], token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}` }
-        ])
-      );
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
         trust_mode: "unknown",
         intent_scope: "none",
@@ -489,13 +507,14 @@ function agentixMiddleware(sdk) {
         version: "0.2.0",
         tenant_id: sdk.getResolvedTenantId(),
         deployment_id: sdk.getDeploymentId(),
+        instructions: agentInstructions(ttlSec),
+        token_ttl_seconds: ttlSec,
         discovery: {
           well_known: `${baseUrl}/.well-known/ai-agent.json`,
           token_endpoint: `${baseUrl}/agent/v1/declare_intent`,
-          note: "GET /agent/v1/declare_intent?intent=<intent> also supported for non-POST clients"
+          note: "Both GET (?intent=<intent>) and POST (JSON body) are accepted at token_endpoint."
         },
-        intents: [...registry.keys()],
-        tools
+        tools: buildTools(sdk, baseUrl)
       }, { headers: { "cache-control": "no-store" } });
     }
     if (pathname === "/agent/v1/declare_intent" && (req.method === "POST" || req.method === "GET")) {
@@ -525,12 +544,15 @@ function agentixMiddleware(sdk) {
           policy_id: "intent-validation",
           metadata: { supplied_intent: intentVal ?? null }
         }));
-        return server_js.NextResponse.json({ error: "invalid_intent", valid_intents: validIntents }, { status: 400 });
+        return server_js.NextResponse.json({
+          error: "invalid_intent",
+          valid_intents: validIntents,
+          hint: `Use one of the valid_intents above. Example: GET ${baseUrl}/agent/v1/declare_intent?intent=${validIntents[0] ?? "<intent>"}`
+        }, { status: 400 });
       }
       const intent = intentVal;
-      const ttl = sdk.config.tokenTtlMs ?? 15 * 60 * 1e3;
       const iat = Math.floor(Date.now() / 1e3);
-      const exp = iat + Math.floor(ttl / 1e3);
+      const exp = iat + ttlSec;
       const raw = await issueTokenWeb(tokenSecret, { intent, domain: sdk.getResolvedDomain(), binding: fp, iat, exp });
       const jti = tokenIdWeb(raw);
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
@@ -547,19 +569,13 @@ function agentixMiddleware(sdk) {
         token_type: "Bearer",
         token_id: jti,
         intent,
-        expires_in: exp - iat
+        expires_in: ttlSec,
+        usage: `Set header: Authorization: Bearer ${raw.slice(0, 20)}... on requests to the ${intent} routes.`
       });
     }
     const isHumanPage = !pathname.startsWith("/api/") && !pathname.startsWith("/agent/") && !pathname.startsWith("/_next/") && !pathname.startsWith("/favicon");
     const score = agentScore(req);
     if (isHumanPage && score >= 0.5) {
-      const registry = sdk.getIntentRegistry();
-      const tools = Object.fromEntries(
-        [...registry.entries()].map(([intent, entry]) => [
-          intent,
-          { routes: [...entry.routes], token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}` }
-        ])
-      );
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
         trust_mode: "unmanaged_automation",
         intent_scope: "none",
@@ -578,12 +594,15 @@ function agentixMiddleware(sdk) {
       return server_js.NextResponse.json({
         service: "agentix-intent-sdk",
         version: "0.2.0",
-        message: "AI agent detected. Use the agent API instead of the human-facing site.",
-        tenant_id: sdk.getResolvedTenantId(),
-        deployment_id: sdk.getDeploymentId(),
-        discovery: { well_known: `${baseUrl}/.well-known/ai-agent.json`, token_endpoint: `${baseUrl}/agent/v1/declare_intent` },
-        intents: [...registry.keys()],
-        tools
+        message: "You are an AI agent accessing a human-facing page. This site exposes a structured agent API \u2014 use it instead of scraping HTML.",
+        instructions: agentInstructions(ttlSec),
+        token_ttl_seconds: ttlSec,
+        discovery: {
+          well_known: `${baseUrl}/.well-known/ai-agent.json`,
+          token_endpoint: `${baseUrl}/agent/v1/declare_intent`,
+          note: "Both GET (?intent=<intent>) and POST (JSON body) are accepted at token_endpoint."
+        },
+        tools: buildTools(sdk, baseUrl)
       }, { headers: { "cache-control": "no-store" } });
     }
     if (req.method === "GET" && pathname === "/robots.txt") {
@@ -617,7 +636,12 @@ function secure(sdk, intent, handler, opts = {}) {
     const baseUrl = req.nextUrl.origin;
     if (!raw) {
       return server_js.NextResponse.json(
-        { error: "missing_token", agent_discovery: `${baseUrl}/.well-known/ai-agent.json` },
+        {
+          error: "missing_token",
+          message: "This route requires an intent token. Visit agent_discovery to see available tools and their token_url.",
+          agent_discovery: `${baseUrl}/.well-known/ai-agent.json`,
+          token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+        },
         { status: 401, headers: { "www-authenticate": 'Bearer realm="agentix", error="missing_token"' } }
       );
     }
@@ -625,10 +649,21 @@ function secure(sdk, intent, handler, opts = {}) {
     if (verdict.decision === "allow") return handler(req, ctx);
     const reason = verdict.reason ?? "denied";
     if (reason === "missing_token" || reason === "invalid_token") {
-      return server_js.NextResponse.json({ error: reason, agent_discovery: `${baseUrl}/.well-known/ai-agent.json` }, { status: 401 });
+      return server_js.NextResponse.json({
+        error: reason,
+        message: "Token is missing or expired. Fetch a new one from token_url.",
+        agent_discovery: `${baseUrl}/.well-known/ai-agent.json`,
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+      }, { status: 401 });
     }
     if (reason === "out_of_scope") {
-      return server_js.NextResponse.json({ error: "out_of_scope", required_intent: verdict.required_intent ?? intent }, { status: 403 });
+      const required = verdict.required_intent ?? intent;
+      return server_js.NextResponse.json({
+        error: "out_of_scope",
+        message: `Your token is scoped to a different intent. Get a new token for "${required}" from token_url.`,
+        required_intent: required,
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(required)}`
+      }, { status: 403 });
     }
     return server_js.NextResponse.json({ error: reason }, { status: 401 });
   };

package/dist/index.d.cts

@@ -73,6 +73,9 @@ interface AgentixSDKConfig {
     /** Map of intent → route string (e.g. { read_jobs: 'GET /api/jobs' }).
      *  Registered at init time so routes appear in discovery before any request. */
     routes?: Record<string, string>;
+    /** Human-readable description per intent, shown in agent discovery responses.
+     *  e.g. { read_jobs: 'Browse open job listings', read_cvs: 'Access candidate CVs' } */
+    descriptions?: Record<string, string>;
 }
 
 declare class AgentixSDK {

package/dist/index.d.ts

@@ -73,6 +73,9 @@ interface AgentixSDKConfig {
     /** Map of intent → route string (e.g. { read_jobs: 'GET /api/jobs' }).
      *  Registered at init time so routes appear in discovery before any request. */
     routes?: Record<string, string>;
+    /** Human-readable description per intent, shown in agent discovery responses.
+     *  e.g. { read_jobs: 'Browse open job listings', read_cvs: 'Access candidate CVs' } */
+    descriptions?: Record<string, string>;
 }
 
 declare class AgentixSDK {

package/dist/index.js

@@ -457,6 +457,30 @@ function auditRow(sdk, req, route, status, fp, fields) {
     ...fields
   };
 }
+function buildTools(sdk, baseUrl) {
+  const registry = sdk.getIntentRegistry();
+  const descriptions = sdk.config.descriptions ?? {};
+  return Object.fromEntries(
+    [...registry.entries()].map(([intent, entry]) => {
+      const tool = {
+        routes: [...entry.routes],
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+      };
+      if (descriptions[intent]) tool.description = descriptions[intent];
+      return [intent, tool];
+    })
+  );
+}
+function agentInstructions(ttlSec) {
+  return [
+    "1. Pick the tool below that matches what you need to do.",
+    `2. Fetch the tool's token_url with a GET request (no body, no auth required). You will receive JSON containing an access_token. Tokens are valid for ${ttlSec} seconds.`,
+    '3. Include the token in the Authorization header on every API request: "Authorization: Bearer <access_token>"',
+    "4. If you receive HTTP 401 (missing_token or invalid_token), your token is missing or expired \u2014 fetch a new one from the same token_url.",
+    "5. If you receive HTTP 403 (out_of_scope), your token's intent does not cover this route. Get a new token from the token_url of the correct tool.",
+    "6. Each token is scoped to exactly one intent. Use a different token for each capability."
+  ];
+}
 function agentixMiddleware(sdk) {
   return async (req) => {
     await sdk.ensureInitialized();
@@ -466,14 +490,8 @@ function agentixMiddleware(sdk) {
     const cp = (sdk.config.controlPlaneUrl ?? "https://agentix-control-plane.onrender.com").replace(/\/$/, "");
     const licenseKey = sdk.config.licenseKey;
     const tokenSecret = sdk.getResolvedTokenSecret();
+    const ttlSec = Math.floor((sdk.config.tokenTtlMs ?? 15 * 60 * 1e3) / 1e3);
     if (req.method === "GET" && pathname === "/.well-known/ai-agent.json") {
-      const registry = sdk.getIntentRegistry();
-      const tools = Object.fromEntries(
-        [...registry.entries()].map(([intent, entry]) => [
-          intent,
-          { routes: [...entry.routes], token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}` }
-        ])
-      );
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
         trust_mode: "unknown",
         intent_scope: "none",
@@ -487,13 +505,14 @@ function agentixMiddleware(sdk) {
         version: "0.2.0",
         tenant_id: sdk.getResolvedTenantId(),
         deployment_id: sdk.getDeploymentId(),
+        instructions: agentInstructions(ttlSec),
+        token_ttl_seconds: ttlSec,
         discovery: {
           well_known: `${baseUrl}/.well-known/ai-agent.json`,
           token_endpoint: `${baseUrl}/agent/v1/declare_intent`,
-          note: "GET /agent/v1/declare_intent?intent=<intent> also supported for non-POST clients"
+          note: "Both GET (?intent=<intent>) and POST (JSON body) are accepted at token_endpoint."
         },
-        intents: [...registry.keys()],
-        tools
+        tools: buildTools(sdk, baseUrl)
       }, { headers: { "cache-control": "no-store" } });
     }
     if (pathname === "/agent/v1/declare_intent" && (req.method === "POST" || req.method === "GET")) {
@@ -523,12 +542,15 @@ function agentixMiddleware(sdk) {
           policy_id: "intent-validation",
           metadata: { supplied_intent: intentVal ?? null }
         }));
-        return NextResponse.json({ error: "invalid_intent", valid_intents: validIntents }, { status: 400 });
+        return NextResponse.json({
+          error: "invalid_intent",
+          valid_intents: validIntents,
+          hint: `Use one of the valid_intents above. Example: GET ${baseUrl}/agent/v1/declare_intent?intent=${validIntents[0] ?? "<intent>"}`
+        }, { status: 400 });
       }
       const intent = intentVal;
-      const ttl = sdk.config.tokenTtlMs ?? 15 * 60 * 1e3;
       const iat = Math.floor(Date.now() / 1e3);
-      const exp = iat + Math.floor(ttl / 1e3);
+      const exp = iat + ttlSec;
       const raw = await issueTokenWeb(tokenSecret, { intent, domain: sdk.getResolvedDomain(), binding: fp, iat, exp });
       const jti = tokenIdWeb(raw);
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
@@ -545,19 +567,13 @@ function agentixMiddleware(sdk) {
         token_type: "Bearer",
         token_id: jti,
         intent,
-        expires_in: exp - iat
+        expires_in: ttlSec,
+        usage: `Set header: Authorization: Bearer ${raw.slice(0, 20)}... on requests to the ${intent} routes.`
       });
     }
     const isHumanPage = !pathname.startsWith("/api/") && !pathname.startsWith("/agent/") && !pathname.startsWith("/_next/") && !pathname.startsWith("/favicon");
     const score = agentScore(req);
     if (isHumanPage && score >= 0.5) {
-      const registry = sdk.getIntentRegistry();
-      const tools = Object.fromEntries(
-        [...registry.entries()].map(([intent, entry]) => [
-          intent,
-          { routes: [...entry.routes], token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}` }
-        ])
-      );
       void shipAudit2(cp, licenseKey, auditRow(sdk, req, pathname, 200, fp, {
         trust_mode: "unmanaged_automation",
         intent_scope: "none",
@@ -576,12 +592,15 @@ function agentixMiddleware(sdk) {
       return NextResponse.json({
         service: "agentix-intent-sdk",
         version: "0.2.0",
-        message: "AI agent detected. Use the agent API instead of the human-facing site.",
-        tenant_id: sdk.getResolvedTenantId(),
-        deployment_id: sdk.getDeploymentId(),
-        discovery: { well_known: `${baseUrl}/.well-known/ai-agent.json`, token_endpoint: `${baseUrl}/agent/v1/declare_intent` },
-        intents: [...registry.keys()],
-        tools
+        message: "You are an AI agent accessing a human-facing page. This site exposes a structured agent API \u2014 use it instead of scraping HTML.",
+        instructions: agentInstructions(ttlSec),
+        token_ttl_seconds: ttlSec,
+        discovery: {
+          well_known: `${baseUrl}/.well-known/ai-agent.json`,
+          token_endpoint: `${baseUrl}/agent/v1/declare_intent`,
+          note: "Both GET (?intent=<intent>) and POST (JSON body) are accepted at token_endpoint."
+        },
+        tools: buildTools(sdk, baseUrl)
       }, { headers: { "cache-control": "no-store" } });
     }
     if (req.method === "GET" && pathname === "/robots.txt") {
@@ -615,7 +634,12 @@ function secure(sdk, intent, handler, opts = {}) {
     const baseUrl = req.nextUrl.origin;
     if (!raw) {
       return NextResponse.json(
-        { error: "missing_token", agent_discovery: `${baseUrl}/.well-known/ai-agent.json` },
+        {
+          error: "missing_token",
+          message: "This route requires an intent token. Visit agent_discovery to see available tools and their token_url.",
+          agent_discovery: `${baseUrl}/.well-known/ai-agent.json`,
+          token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+        },
         { status: 401, headers: { "www-authenticate": 'Bearer realm="agentix", error="missing_token"' } }
       );
     }
@@ -623,10 +647,21 @@ function secure(sdk, intent, handler, opts = {}) {
     if (verdict.decision === "allow") return handler(req, ctx);
     const reason = verdict.reason ?? "denied";
     if (reason === "missing_token" || reason === "invalid_token") {
-      return NextResponse.json({ error: reason, agent_discovery: `${baseUrl}/.well-known/ai-agent.json` }, { status: 401 });
+      return NextResponse.json({
+        error: reason,
+        message: "Token is missing or expired. Fetch a new one from token_url.",
+        agent_discovery: `${baseUrl}/.well-known/ai-agent.json`,
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(intent)}`
+      }, { status: 401 });
     }
     if (reason === "out_of_scope") {
-      return NextResponse.json({ error: "out_of_scope", required_intent: verdict.required_intent ?? intent }, { status: 403 });
+      const required = verdict.required_intent ?? intent;
+      return NextResponse.json({
+        error: "out_of_scope",
+        message: `Your token is scoped to a different intent. Get a new token for "${required}" from token_url.`,
+        required_intent: required,
+        token_url: `${baseUrl}/agent/v1/declare_intent?intent=${encodeURIComponent(required)}`
+      }, { status: 403 });
     }
     return NextResponse.json({ error: reason }, { status: 401 });
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentix-security/nextjs",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Agentix Next.js adapter — AI agent intent-based authorization for Next.js apps",
   "type": "module",
   "main": "./dist/index.cjs",