@astrasyncai/verification-gateway 2.1.0 → 2.2.0

package/dist/git-trigger/git-hooks.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-jJnPXStc.mjs';
-import '../types-CxQwJKbd.mjs';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-DE0ooQJ6.mjs';
+import '../types-CrVMq_Td.mjs';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/git-trigger/git-hooks.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-79qS7aON.js';
-import '../types-CxQwJKbd.js';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-rigu2bH3.js';
+import '../types-CrVMq_Td.js';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/{index-BY8yQ8N8.d.mts → index-BMZdjGT4.d.mts}

@@ -1,4 +1,4 @@
-import { A as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-CxQwJKbd.mjs';
+import { A as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-CrVMq_Td.mjs';
 
 /**
  * AgentClient — Credential Presentation
@@ -12,6 +12,10 @@ interface AgentClientConfig {
     verifyUrl?: string;
     challengeUrl?: string;
     pdlss?: AstraSyncCredentials['pdlss'];
+    /** Base URL for AstraSync API (used for ownership check). Defaults to api.astrasync.ai */
+    apiBaseUrl?: string;
+    /** API key used to authenticate ownership check + other authenticated calls. */
+    apiKey?: string;
 }
 interface FetchOptions extends RequestInit {
     purpose?: string;
@@ -19,7 +23,25 @@ interface FetchOptions extends RequestInit {
 }
 declare class AgentClient {
     private credentials;
+    private apiBaseUrl;
+    private apiKey;
     constructor(config: AgentClientConfig);
+    /**
+     * Async factory that validates the API key's account owns the configured
+     * ASTRA-id before returning a usable client. Refuses to initialise on
+     * mismatch so a stolen ASTRA-id cannot be paired with a valid (different)
+     * API key.
+     *
+     * Set env `ASTRASYNC_SKIP_OWNERSHIP_CHECK=true` to bypass — intended for
+     * test environments only.
+     */
+    static create(config: AgentClientConfig): Promise<AgentClient>;
+    /**
+     * Calls GET /api/agents/:astraId/ownership with the configured API key.
+     * Returns true only when the backend confirms this API key's account
+     * owns the configured agent.
+     */
+    private verifyOwnership;
     /**
      * Make an HTTP request with AstraSync headers automatically injected.
      */
@@ -183,6 +205,23 @@ interface RecordDecisionResult {
  */
 declare function recordDecision(config: GatewayConfig, params: RecordDecisionParams): Promise<RecordDecisionResult>;
 
+/**
+ * Agent-side SDK errors.
+ */
+declare class AstraSyncSdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when the API key used to initialise AgentClient is not owned by
+ * the same account that registered the configured ASTRA-id. Blocks the
+ * client from doing anything under a mismatched identity.
+ */
+declare class OwnershipMismatchError extends AstraSyncSdkError {
+    readonly astraId: string;
+    constructor(astraId: string);
+}
+
 /**
  * Agent-Side SDK Module
  *
@@ -192,15 +231,19 @@ declare function recordDecision(config: GatewayConfig, params: RecordDecisionPar
 
 type index_AgentClient = AgentClient;
 declare const index_AgentClient: typeof AgentClient;
+type index_AstraSyncSdkError = AstraSyncSdkError;
+declare const index_AstraSyncSdkError: typeof AstraSyncSdkError;
 type index_ChallengeHandler = ChallengeHandler;
 declare const index_ChallengeHandler: typeof ChallengeHandler;
+type index_OwnershipMismatchError = OwnershipMismatchError;
+declare const index_OwnershipMismatchError: typeof OwnershipMismatchError;
 type index_PDLSSConfig = PDLSSConfig;
 type index_TransportPDLSS = TransportPDLSS;
 declare const index_formatPDLSSForTransport: typeof formatPDLSSForTransport;
 declare const index_parsePDLSSFromTransport: typeof parsePDLSSFromTransport;
 declare const index_recordDecision: typeof recordDecision;
 declare namespace index {
-  export { index_AgentClient as AgentClient, index_ChallengeHandler as ChallengeHandler, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
+  export { index_AgentClient as AgentClient, index_AstraSyncSdkError as AstraSyncSdkError, index_ChallengeHandler as ChallengeHandler, index_OwnershipMismatchError as OwnershipMismatchError, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
 }
 
-export { AgentClient as A, ChallengeHandler as C, type PDLSSConfig as P, type TransportPDLSS as T, formatPDLSSForTransport as f, index as i, parsePDLSSFromTransport as p, recordDecision as r };
+export { AgentClient as A, ChallengeHandler as C, OwnershipMismatchError as O, type PDLSSConfig as P, type TransportPDLSS as T, AstraSyncSdkError as a, formatPDLSSForTransport as f, index as i, parsePDLSSFromTransport as p, recordDecision as r };

package/dist/{index-3NRaBNvp.d.mts → index-DlsYN3Et.d.mts}

@@ -1,4 +1,4 @@
-import { A as AstraSyncCredentials, g as ProtocolTransport } from './types-CxQwJKbd.mjs';
+import { A as AstraSyncCredentials, g as ProtocolTransport } from './types-CrVMq_Td.mjs';
 import { JWK } from 'jose';
 
 /**

package/dist/{index-CtYSYwn3.d.ts → index-Dm2xA6j1.d.ts}

@@ -1,4 +1,4 @@
-import { A as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-CxQwJKbd.js';
+import { A as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-CrVMq_Td.js';
 
 /**
  * AgentClient — Credential Presentation
@@ -12,6 +12,10 @@ interface AgentClientConfig {
     verifyUrl?: string;
     challengeUrl?: string;
     pdlss?: AstraSyncCredentials['pdlss'];
+    /** Base URL for AstraSync API (used for ownership check). Defaults to api.astrasync.ai */
+    apiBaseUrl?: string;
+    /** API key used to authenticate ownership check + other authenticated calls. */
+    apiKey?: string;
 }
 interface FetchOptions extends RequestInit {
     purpose?: string;
@@ -19,7 +23,25 @@ interface FetchOptions extends RequestInit {
 }
 declare class AgentClient {
     private credentials;
+    private apiBaseUrl;
+    private apiKey;
     constructor(config: AgentClientConfig);
+    /**
+     * Async factory that validates the API key's account owns the configured
+     * ASTRA-id before returning a usable client. Refuses to initialise on
+     * mismatch so a stolen ASTRA-id cannot be paired with a valid (different)
+     * API key.
+     *
+     * Set env `ASTRASYNC_SKIP_OWNERSHIP_CHECK=true` to bypass — intended for
+     * test environments only.
+     */
+    static create(config: AgentClientConfig): Promise<AgentClient>;
+    /**
+     * Calls GET /api/agents/:astraId/ownership with the configured API key.
+     * Returns true only when the backend confirms this API key's account
+     * owns the configured agent.
+     */
+    private verifyOwnership;
     /**
      * Make an HTTP request with AstraSync headers automatically injected.
      */
@@ -183,6 +205,23 @@ interface RecordDecisionResult {
  */
 declare function recordDecision(config: GatewayConfig, params: RecordDecisionParams): Promise<RecordDecisionResult>;
 
+/**
+ * Agent-side SDK errors.
+ */
+declare class AstraSyncSdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when the API key used to initialise AgentClient is not owned by
+ * the same account that registered the configured ASTRA-id. Blocks the
+ * client from doing anything under a mismatched identity.
+ */
+declare class OwnershipMismatchError extends AstraSyncSdkError {
+    readonly astraId: string;
+    constructor(astraId: string);
+}
+
 /**
  * Agent-Side SDK Module
  *
@@ -192,15 +231,19 @@ declare function recordDecision(config: GatewayConfig, params: RecordDecisionPar
 
 type index_AgentClient = AgentClient;
 declare const index_AgentClient: typeof AgentClient;
+type index_AstraSyncSdkError = AstraSyncSdkError;
+declare const index_AstraSyncSdkError: typeof AstraSyncSdkError;
 type index_ChallengeHandler = ChallengeHandler;
 declare const index_ChallengeHandler: typeof ChallengeHandler;
+type index_OwnershipMismatchError = OwnershipMismatchError;
+declare const index_OwnershipMismatchError: typeof OwnershipMismatchError;
 type index_PDLSSConfig = PDLSSConfig;
 type index_TransportPDLSS = TransportPDLSS;
 declare const index_formatPDLSSForTransport: typeof formatPDLSSForTransport;
 declare const index_parsePDLSSFromTransport: typeof parsePDLSSFromTransport;
 declare const index_recordDecision: typeof recordDecision;
 declare namespace index {
-  export { index_AgentClient as AgentClient, index_ChallengeHandler as ChallengeHandler, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
+  export { index_AgentClient as AgentClient, index_AstraSyncSdkError as AstraSyncSdkError, index_ChallengeHandler as ChallengeHandler, index_OwnershipMismatchError as OwnershipMismatchError, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
 }
 
-export { AgentClient as A, ChallengeHandler as C, type PDLSSConfig as P, type TransportPDLSS as T, formatPDLSSForTransport as f, index as i, parsePDLSSFromTransport as p, recordDecision as r };
+export { AgentClient as A, ChallengeHandler as C, OwnershipMismatchError as O, type PDLSSConfig as P, type TransportPDLSS as T, AstraSyncSdkError as a, formatPDLSSForTransport as f, index as i, parsePDLSSFromTransport as p, recordDecision as r };

package/dist/{index-CME6r4uH.d.ts → index-gM-lgX_X.d.ts}

@@ -1,4 +1,4 @@
-import { A as AstraSyncCredentials, g as ProtocolTransport } from './types-CxQwJKbd.js';
+import { A as AstraSyncCredentials, g as ProtocolTransport } from './types-CrVMq_Td.js';
 import { JWK } from 'jose';
 
 /**

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, c as VerificationRequest, V as VerificationResult } from './types-CxQwJKbd.mjs';
-export { A as AstraSyncCredentials, d as CommerceShieldProps, C as CounterpartyType, e as EnhancedVerificationResult, E as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-CxQwJKbd.mjs';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, c as getCapabilities, e as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-BhvuJSrH.mjs';
-export { e as express } from './express-CtwDIZyF.mjs';
-export { n as nextjs } from './nextjs-BQyMCSx_.mjs';
-export { i as transport } from './index-3NRaBNvp.mjs';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-BY8yQ8N8.mjs';
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, c as VerificationRequest, V as VerificationResult } from './types-CrVMq_Td.mjs';
+export { A as AstraSyncCredentials, d as CommerceShieldProps, C as CounterpartyType, e as EnhancedVerificationResult, E as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-CrVMq_Td.mjs';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, c as getCapabilities, e as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-7fa9H0qa.mjs';
+export { e as express } from './express-C9KqJNWV.mjs';
+export { n as nextjs } from './nextjs-BEqidT0U.mjs';
+export { i as transport } from './index-DlsYN3Et.mjs';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-BMZdjGT4.mjs';
 import 'express';
 import 'next/server';
 import 'jose';

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, c as VerificationRequest, V as VerificationResult } from './types-CxQwJKbd.js';
-export { A as AstraSyncCredentials, d as CommerceShieldProps, C as CounterpartyType, e as EnhancedVerificationResult, E as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-CxQwJKbd.js';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, c as getCapabilities, e as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-BlyVSC_S.js';
-export { e as express } from './express-Bcl-uBUE.js';
-export { n as nextjs } from './nextjs-CEldnIJ9.js';
-export { i as transport } from './index-CME6r4uH.js';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-CtYSYwn3.js';
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, c as VerificationRequest, V as VerificationResult } from './types-CrVMq_Td.js';
+export { A as AstraSyncCredentials, d as CommerceShieldProps, C as CounterpartyType, e as EnhancedVerificationResult, E as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-CrVMq_Td.js';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, c as getCapabilities, e as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-CP9C9Qu0.js';
+export { e as express } from './express-DpwYW08E.js';
+export { n as nextjs } from './nextjs-yNzimC3a.js';
+export { i as transport } from './index-gM-lgX_X.js';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-Dm2xA6j1.js';
 import 'express';
 import 'next/server';
 import 'jose';

package/dist/index.js

@@ -278,21 +278,33 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.isSubAgentRequest) body.isSubAgentRequest = requestData.isSubAgentRequest;
   if (requestData.parentAgentId) body.parentAgentId = requestData.parentAgentId;
   if (requestData.subAgentDepth !== void 0) body.subAgentDepth = requestData.subAgentDepth;
-  if (requestData.enableRuntimeChallenge) body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
+  if (requestData.enableRuntimeChallenge)
+    body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
   if (requestData.createSession) body.createSession = requestData.createSession;
   if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
   if (requestData.counterpartyType) body.counterpartyType = requestData.counterpartyType;
   if (requestData.counterpartyUrl) body.counterpartyUrl = requestData.counterpartyUrl;
-  if (requestData.runtimeChallengeOptions) body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (requestData.runtimeChallengeOptions)
+    body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
+    const meta = {
+      ...requestData.clientIp && { sourceIp: requestData.clientIp },
+      ...requestData.userAgent && { userAgent: requestData.userAgent },
+      ...requestData.callerMetadata
+    };
+    if (Object.keys(meta).length > 0) body.callerMetadata = meta;
+  }
   const headers = {
     "Content-Type": "application/json",
     ...config.customHeaders
   };
-  if (config.apiKey) {
-    headers["X-API-Key"] = config.apiKey;
-  }
   if (credentials.authorizationHeader) {
     headers["Authorization"] = credentials.authorizationHeader;
+  } else if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+  }
+  if (config.apiKey) {
+    headers["X-API-Key"] = config.apiKey;
   }
   try {
     const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
@@ -393,16 +405,11 @@ async function verify(config, request) {
   } : void 0;
   const trustScore = agent?.trustScore || 0;
   const isOrgMember = false;
-  const accessLevel = determineAccessLevel(
-    true,
-    trustScore,
-    isOrgMember,
-    {
-      "read-only": 20,
-      standard: mergedConfig.minTrustScore || 40,
-      full: mergedConfig.minTrustScoreForFull || 70
-    }
-  );
+  const accessLevel = determineAccessLevel(true, trustScore, isOrgMember, {
+    "read-only": 20,
+    standard: mergedConfig.minTrustScore || 40,
+    full: mergedConfig.minTrustScoreForFull || 70
+  });
   const result = {
     verified: true,
     accessLevel,
@@ -424,7 +431,9 @@ async function verify(config, request) {
   if (result.recommendation === "deny") {
     result.verified = false;
     result.accessLevel = "none";
-    result.denialReasons = result.recommendationReasons || ["Access denied by AstraSync recommendation"];
+    result.denialReasons = result.recommendationReasons || [
+      "Access denied by AstraSync recommendation"
+    ];
     if (result.runtimeChallenge) {
       result.guidance = {
         message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
@@ -446,7 +455,10 @@ async function verify(config, request) {
 }
 async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
-  if (config.apiKey) headers["X-API-Key"] = config.apiKey;
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+    headers["X-API-Key"] = config.apiKey;
+  }
   await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
     method: "POST",
     headers,
@@ -744,18 +756,28 @@ function createMiddleware(options) {
         return;
       }
       const shouldRecordDecisions = recordDecisions !== false;
+      const forwardedFor = req.headers["x-forwarded-for"];
+      const forwardedForStr = Array.isArray(forwardedFor) ? forwardedFor.join(", ") : forwardedFor;
+      const originalClientIp = forwardedForStr ? forwardedForStr.split(",")[0].trim() : req.ip;
+      const agentCardUrl = typeof req.headers["x-astrasync-agent-card"] === "string" ? req.headers["x-astrasync-agent-card"] : void 0;
       const result = await verify(config, {
         credentials,
         purpose,
         action: req.method.toLowerCase(),
         resource: req.path,
-        clientIp: req.ip,
-        userAgent: req.headers["user-agent"],
         createSession: shouldRecordDecisions,
         counterpartyUrl,
         counterpartyType: config.counterpartyType || "api",
         enableRuntimeChallenge,
-        durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration
+        durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
+        callerMetadata: {
+          sourceIp: originalClientIp,
+          userAgent: req.headers["user-agent"],
+          referer: req.headers.referer,
+          host: req.headers.host,
+          forwardedFor: forwardedForStr,
+          agentCardUrl
+        }
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;
@@ -1027,7 +1049,13 @@ function generateCommerceShieldHtml(result, options) {
   `.trim();
 }
 function createMiddleware2(options) {
-  const { routes = [], skipPaths = [], showCommerceShield = true, enableRuntimeChallenge = true, ...config } = options;
+  const {
+    routes = [],
+    skipPaths = [],
+    showCommerceShield = true,
+    enableRuntimeChallenge = true,
+    ...config
+  } = options;
   return async function middleware(request) {
     const { NextResponse } = await import("next/server");
     const pathname = request.nextUrl.pathname;
@@ -1139,17 +1167,25 @@ function createMiddleware2(options) {
       }
       return NextResponse.redirect(new URL("/unauthorized", request.url));
     }
+    const forwardedFor = request.headers.get("x-forwarded-for") || void 0;
+    const originalClientIp = forwardedFor?.split(",")[0]?.trim();
     const result = await verify(config, {
       credentials,
       purpose,
       action: request.method.toLowerCase(),
       resource: pathname,
-      clientIp: request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || void 0,
-      userAgent: request.headers.get("user-agent") || void 0,
       counterpartyUrl,
       counterpartyType: config.counterpartyType || "website",
       enableRuntimeChallenge,
-      durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration
+      durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
+      callerMetadata: {
+        sourceIp: originalClientIp,
+        userAgent: request.headers.get("user-agent") || void 0,
+        referer: request.headers.get("referer") || void 0,
+        host: request.headers.get("host") || void 0,
+        forwardedFor,
+        agentCardUrl: request.headers.get("x-astrasync-agent-card") || void 0
+      }
     });
     if (!hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
       if (pathname.startsWith("/api/")) {
@@ -3771,14 +3807,35 @@ function extractCredentialsFromProtocol(protocol, context) {
 var agent_exports = {};
 __export(agent_exports, {
   AgentClient: () => AgentClient,
+  AstraSyncSdkError: () => AstraSyncSdkError,
   ChallengeHandler: () => ChallengeHandler,
+  OwnershipMismatchError: () => OwnershipMismatchError,
   formatPDLSSForTransport: () => formatPDLSSForTransport,
   parsePDLSSFromTransport: () => parsePDLSSFromTransport,
   recordDecision: () => recordDecision2
 });
 
+// src/agent/errors.ts
+var AstraSyncSdkError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "AstraSyncSdkError";
+    this.code = code;
+  }
+};
+var OwnershipMismatchError = class extends AstraSyncSdkError {
+  constructor(astraId) {
+    super(
+      "ownership_mismatch",
+      `The configured API key does not own agent ${astraId}. Refusing to initialise.`
+    );
+    this.name = "OwnershipMismatchError";
+    this.astraId = astraId;
+  }
+};
+
 // src/agent/client.ts
-var AgentClient = class {
+var AgentClient = class _AgentClient {
   constructor(config) {
     this.credentials = {
       agentId: config.agentId,
@@ -3786,6 +3843,49 @@ var AgentClient = class {
       challengeUrl: config.challengeUrl,
       pdlss: config.pdlss
     };
+    this.apiBaseUrl = config.apiBaseUrl ?? "https://api.astrasync.ai";
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Async factory that validates the API key's account owns the configured
+   * ASTRA-id before returning a usable client. Refuses to initialise on
+   * mismatch so a stolen ASTRA-id cannot be paired with a valid (different)
+   * API key.
+   *
+   * Set env `ASTRASYNC_SKIP_OWNERSHIP_CHECK=true` to bypass — intended for
+   * test environments only.
+   */
+  static async create(config) {
+    const client = new _AgentClient(config);
+    const skip = typeof process !== "undefined" && process.env?.ASTRASYNC_SKIP_OWNERSHIP_CHECK === "true";
+    if (skip) return client;
+    if (!config.apiKey) {
+      throw new OwnershipMismatchError(config.agentId);
+    }
+    const owned = await client.verifyOwnership();
+    if (!owned) throw new OwnershipMismatchError(config.agentId);
+    return client;
+  }
+  /**
+   * Calls GET /api/agents/:astraId/ownership with the configured API key.
+   * Returns true only when the backend confirms this API key's account
+   * owns the configured agent.
+   */
+  async verifyOwnership() {
+    if (!this.apiKey) return false;
+    const url = `${this.apiBaseUrl.replace(/\/+$/, "")}/api/agents/${encodeURIComponent(
+      this.credentials.agentId
+    )}/ownership`;
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (!resp.ok) return false;
+    const body = await resp.json().catch(() => null);
+    return Boolean(body?.data?.owned);
   }
   /**
    * Make an HTTP request with AstraSync headers automatically injected.