@ghostgate/sdk 0.1.2 → 0.1.3

package/README.md

@@ -38,6 +38,9 @@ const sdk = new GhostAgent({
   privateKey: process.env.GHOST_SIGNER_PRIVATE_KEY as `0x${string}`,
   baseUrl: process.env.GHOST_BASE_URL,
   serviceSlug: "agent-18755",
+  // Optional x402 compatibility mode:
+  // authMode: "x402",
+  // x402Scheme: "ghost-eip712-credit-v1",
 });
 
 await sdk.connect();

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type GhostAgentConfig = {
     chainId?: number;
     serviceSlug?: string;
     creditCost?: number;
+    authMode?: "ghost-eip712" | "x402";
+    x402Scheme?: string;
 };
 export type ConnectResult = {
     connected: boolean;
@@ -16,6 +18,10 @@ export type ConnectResult = {
     endpoint: string;
     status: number;
     payload: unknown;
+    x402?: {
+        paymentRequired: unknown | null;
+        paymentResponse: unknown | null;
+    };
 };
 export type TelemetryResult = {
     ok: boolean;
@@ -48,6 +54,44 @@ export type CanaryPayload = {
 };
 export type GhostMerchantConfig = GhostFulfillmentMerchantConfig & {
     serviceSlug: string;
+    ownerPrivateKey?: `0x${string}`;
+};
+type MerchantGatewayConfigResponse = {
+    configured: boolean;
+    config: {
+        ownerAddress: string;
+        readinessStatus: "UNCONFIGURED" | "CONFIGURED" | "LIVE" | "DEGRADED";
+    };
+};
+type MerchantGatewayVerifyResponse = {
+    verified?: boolean;
+    readinessStatus?: "UNCONFIGURED" | "CONFIGURED" | "LIVE" | "DEGRADED";
+    error?: string;
+    canaryUrl?: string;
+    statusCode?: number | null;
+    latencyMs?: number | null;
+};
+type MerchantGatewayDelegatedSignerRegisterResponse = {
+    ok?: boolean;
+    created?: boolean;
+    alreadyActive?: boolean;
+    error?: string;
+};
+export type MerchantActivateOptions = {
+    agentId: string;
+    serviceSlug: string;
+    endpointUrl: string;
+    canaryPath?: string;
+    canaryMethod?: string;
+    signerLabel?: string;
+};
+export type ActivateResult = {
+    status: "LIVE";
+    readiness: "LIVE";
+    config: MerchantGatewayConfigResponse["config"];
+    verify: MerchantGatewayVerifyResponse;
+    signerRegistration: MerchantGatewayDelegatedSignerRegisterResponse;
+    heartbeat: HeartbeatController;
 };
 export declare const buildCanaryPayload: (serviceSlug: string) => CanaryPayload;
 export declare const createCanaryHandler: (serviceSlug: string) => (_req?: unknown, res?: unknown) => unknown;
@@ -60,6 +104,8 @@ export declare class GhostAgent {
     private readonly telemetryServiceSlug;
     private readonly serviceSlug;
     private readonly creditCost;
+    private readonly authMode;
+    private readonly x402Scheme;
     constructor(config?: GhostAgentConfig);
     connect(apiKey?: string): Promise<ConnectResult>;
     pulse(input?: PulseInput): Promise<TelemetryResult>;
@@ -70,9 +116,18 @@ export declare class GhostAgent {
 }
 export declare class GhostMerchant extends GhostFulfillmentMerchant {
     private readonly merchantServiceSlug;
+    private readonly merchantBaseUrl;
+    private readonly ownerPrivateKey;
+    private readonly ownerAddress;
+    private readonly delegatedSignerAddress;
+    private heartbeatController;
     constructor(config: GhostMerchantConfig);
     canaryPayload(): CanaryPayload;
     canaryHandler(): (_req?: unknown, res?: unknown) => unknown;
+    activate(options: MerchantActivateOptions): Promise<ActivateResult>;
+    private fetchGatewayOwnerConfig;
+    private postMerchantSignedWrite;
+    private extractApiErrorMessage;
 }
 export default GhostAgent;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,cAAc,kBAAkB,CAAC;AAEjC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,8BAA8B,GAAG;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAmEF,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,KAAG,aAOxD,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,aAAa,MAAM,MAE7C,OAAO,OAAO,EAAE,MAAM,OAAO,KAAG,OA+BzC,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAgB;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,GAAE,gBAAqB;IAcnC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6DhD,KAAK,CAAC,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IA+BvD,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAkC5D,cAAc,CAAC,OAAO,GAAE,gBAAqB,GAAG,mBAAmB;IAsCnE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF;AAED,qBAAa,aAAc,SAAQ,wBAAwB;IACzD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEjC,MAAM,EAAE,mBAAmB;IASvC,aAAa,IAAI,aAAa;IAI9B,aAAa,YAtPE,OAAO,QAAQ,OAAO,KAAG,OAAO;CAyPhD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,6 +7,13 @@ const DEFAULT_CHAIN_ID = 8453;
 const DEFAULT_SERVICE_SLUG = "connect";
 const DEFAULT_CREDIT_COST = 1;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+const DEFAULT_AUTH_MODE = "ghost-eip712";
+const DEFAULT_X402_SCHEME = "ghost-eip712-credit-v1";
+const DEFAULT_ACTIVATE_CANARY_PATH = "/health";
+const DEFAULT_ACTIVATE_CANARY_METHOD = "GET";
+const DEFAULT_ACTIVATE_SIGNER_LABEL = "sdk-auto";
+const MERCHANT_GATEWAY_AUTH_SCOPE = "agent_gateway";
+const MERCHANT_GATEWAY_AUTH_VERSION = "1";
 const ACCESS_TYPES = {
     Access: [
         { name: "service", type: "string" },
@@ -32,6 +39,18 @@ const parsePayload = async (response) => {
         return null;
     }
 };
+const encodeBase64Json = (value) => Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+const decodeBase64Json = (value) => {
+    if (!value)
+        return null;
+    try {
+        const decoded = Buffer.from(value, "base64").toString("utf8");
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+};
 const deriveAgentId = (serviceSlug) => {
     if (!serviceSlug)
         return null;
@@ -56,6 +75,36 @@ const buildCanaryHeaders = () => ({
     "cache-control": "no-store",
     "content-type": "application/json; charset=utf-8",
 });
+const assertPrivateKey = (value, name) => {
+    if (!value || !/^0x[a-fA-F0-9]{64}$/.test(value)) {
+        throw new Error(`${name} must be a 0x-prefixed 32-byte hex private key.`);
+    }
+    return value;
+};
+const normalizeAddressLower = (value) => value.trim().toLowerCase();
+const createMerchantGatewayAuthPayload = (input) => ({
+    scope: MERCHANT_GATEWAY_AUTH_SCOPE,
+    version: MERCHANT_GATEWAY_AUTH_VERSION,
+    action: input.action,
+    agentId: input.agentId,
+    ownerAddress: normalizeAddressLower(input.ownerAddress),
+    actorAddress: normalizeAddressLower(input.actorAddress),
+    serviceSlug: input.serviceSlug,
+    nonce: randomUUID().replace(/-/g, ""),
+    issuedAt: Math.floor(Date.now() / 1000),
+});
+const buildMerchantGatewayAuthMessage = (payload) => [
+    "Ghost Protocol Merchant Gateway Authorization",
+    `scope:${payload.scope}`,
+    `version:${payload.version}`,
+    `action:${payload.action}`,
+    `agentId:${payload.agentId}`,
+    `serviceSlug:${payload.serviceSlug}`,
+    `ownerAddress:${payload.ownerAddress}`,
+    `actorAddress:${payload.actorAddress}`,
+    `issuedAt:${payload.issuedAt}`,
+    `nonce:${payload.nonce}`,
+].join("\n");
 export const buildCanaryPayload = (serviceSlug) => {
     const normalized = normalizeOptionalString(serviceSlug);
     if (!normalized)
@@ -103,6 +152,8 @@ export class GhostAgent {
         this.creditCost = Number.isFinite(config.creditCost) && (config.creditCost ?? 0) > 0
             ? Math.trunc(config.creditCost)
             : DEFAULT_CREDIT_COST;
+        this.authMode = config.authMode ?? DEFAULT_AUTH_MODE;
+        this.x402Scheme = normalizeOptionalString(config.x402Scheme) ?? DEFAULT_X402_SCHEME;
     }
     async connect(apiKey) {
         const normalizedApiKey = normalizeOptionalString(apiKey) ?? this.apiKey;
@@ -135,17 +186,31 @@ export class GhostAgent {
             message: signedPayload,
         });
         const endpoint = `${this.baseUrl}/api/gate/${encodeURIComponent(this.serviceSlug)}`;
+        const gateHeaders = {
+            accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+        };
+        if (this.authMode === "x402") {
+            gateHeaders["payment-signature"] = encodeBase64Json({
+                x402Version: 2,
+                scheme: this.x402Scheme,
+                network: `eip155:${this.chainId}`,
+                payload: headerPayload,
+                signature,
+            });
+        }
+        else {
+            gateHeaders["x-ghost-sig"] = signature;
+            gateHeaders["x-ghost-payload"] = JSON.stringify(headerPayload);
+            gateHeaders["x-ghost-credit-cost"] = String(this.creditCost);
+        }
         const response = await fetch(endpoint, {
             method: "POST",
-            headers: {
-                "x-ghost-sig": signature,
-                "x-ghost-payload": JSON.stringify(headerPayload),
-                "x-ghost-credit-cost": String(this.creditCost),
-                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
-            },
+            headers: gateHeaders,
             cache: "no-store",
         });
         const responsePayload = await parsePayload(response);
+        const paymentRequired = decodeBase64Json(response.headers.get("payment-required"));
+        const paymentResponse = decodeBase64Json(response.headers.get("payment-response"));
         if (response.ok) {
             this.apiKey = normalizedApiKey;
         }
@@ -155,6 +220,14 @@ export class GhostAgent {
             endpoint,
             status: response.status,
             payload: responsePayload,
+            ...(this.authMode === "x402" || paymentRequired || paymentResponse
+                ? {
+                    x402: {
+                        paymentRequired,
+                        paymentResponse,
+                    },
+                }
+                : {}),
         };
     }
     async pulse(input = {}) {
@@ -261,11 +334,18 @@ export class GhostAgent {
 export class GhostMerchant extends GhostFulfillmentMerchant {
     constructor(config) {
         super(config);
+        this.heartbeatController = null;
         const normalizedServiceSlug = normalizeOptionalString(config.serviceSlug);
         if (!normalizedServiceSlug) {
             throw new Error("GhostMerchant.serviceSlug is required.");
         }
         this.merchantServiceSlug = normalizedServiceSlug;
+        this.merchantBaseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+        this.ownerPrivateKey = config.ownerPrivateKey ? assertPrivateKey(config.ownerPrivateKey, "ownerPrivateKey") : null;
+        this.ownerAddress = this.ownerPrivateKey ? privateKeyToAccount(this.ownerPrivateKey).address.toLowerCase() : null;
+        this.delegatedSignerAddress = config.delegatedPrivateKey
+            ? privateKeyToAccount(assertPrivateKey(config.delegatedPrivateKey, "delegatedPrivateKey")).address.toLowerCase()
+            : null;
     }
     canaryPayload() {
         return buildCanaryPayload(this.merchantServiceSlug);
@@ -273,5 +353,171 @@ export class GhostMerchant extends GhostFulfillmentMerchant {
     canaryHandler() {
         return createCanaryHandler(this.merchantServiceSlug);
     }
+    async activate(options) {
+        const agentId = normalizeOptionalString(options.agentId);
+        const serviceSlug = normalizeOptionalString(options.serviceSlug);
+        const endpointUrl = normalizeOptionalString(options.endpointUrl);
+        const canaryPath = normalizeOptionalString(options.canaryPath) ?? DEFAULT_ACTIVATE_CANARY_PATH;
+        const canaryMethod = (normalizeOptionalString(options.canaryMethod) ?? DEFAULT_ACTIVATE_CANARY_METHOD).toUpperCase();
+        const signerLabel = normalizeOptionalString(options.signerLabel) ?? DEFAULT_ACTIVATE_SIGNER_LABEL;
+        if (!agentId)
+            throw new Error("[activate:validate] agentId is required.");
+        if (!serviceSlug)
+            throw new Error("[activate:validate] serviceSlug is required.");
+        if (!endpointUrl)
+            throw new Error("[activate:validate] endpointUrl is required.");
+        if (!canaryPath.startsWith("/")) {
+            throw new Error("[activate:validate] canaryPath must start with '/'.");
+        }
+        if (canaryMethod !== "GET") {
+            throw new Error("[activate:validate] canaryMethod must be GET.");
+        }
+        if (!this.ownerPrivateKey || !this.ownerAddress) {
+            throw new Error("[activate:owner] ownerPrivateKey is required on GhostMerchant config and must match the indexed agent owner.");
+        }
+        const ownerConfig = await this.fetchGatewayOwnerConfig(agentId);
+        const indexedOwnerAddress = normalizeAddressLower(ownerConfig.config.ownerAddress);
+        if (indexedOwnerAddress !== this.ownerAddress) {
+            throw new Error(`[activate:owner] ownerPrivateKey address ${this.ownerAddress} does not match indexed owner ${indexedOwnerAddress} for agent ${agentId}.`);
+        }
+        const configPayload = (await this.postMerchantSignedWrite("config", {
+            path: "/api/agent-gateway/config",
+            agentId,
+            serviceSlug,
+            ownerAddress: indexedOwnerAddress,
+            body: {
+                endpointUrl,
+                canaryPath,
+                canaryMethod: "GET",
+            },
+        }));
+        const verifyPayload = (await this.postMerchantSignedWrite("verify", {
+            path: "/api/agent-gateway/verify",
+            agentId,
+            serviceSlug,
+            ownerAddress: indexedOwnerAddress,
+            body: {},
+        }));
+        const readiness = verifyPayload.readinessStatus;
+        if (verifyPayload.verified !== true || readiness !== "LIVE") {
+            const detailParts = [
+                verifyPayload.error ? `error=${verifyPayload.error}` : null,
+                verifyPayload.canaryUrl ? `canaryUrl=${verifyPayload.canaryUrl}` : null,
+                typeof verifyPayload.statusCode === "number" ? `statusCode=${verifyPayload.statusCode}` : null,
+                typeof verifyPayload.latencyMs === "number" ? `latencyMs=${verifyPayload.latencyMs}` : null,
+            ].filter(Boolean);
+            throw new Error(`[activate:verify] canary verification did not reach LIVE readiness${detailParts.length ? ` (${detailParts.join(", ")})` : ""}.`);
+        }
+        const signerAddress = this.delegatedSignerAddress ?? indexedOwnerAddress;
+        const signerRegistration = (await this.postMerchantSignedWrite("delegated_signer_register", {
+            path: "/api/agent-gateway/delegated-signers/register",
+            agentId,
+            serviceSlug,
+            ownerAddress: indexedOwnerAddress,
+            body: {
+                signerAddress,
+                label: signerLabel,
+            },
+        }));
+        this.heartbeatController?.stop();
+        const heartbeatAgent = new GhostAgent({
+            baseUrl: this.merchantBaseUrl,
+            agentId,
+            serviceSlug,
+        });
+        this.heartbeatController = heartbeatAgent.startHeartbeat({
+            agentId,
+            serviceSlug,
+            immediate: false,
+        });
+        return {
+            status: "LIVE",
+            readiness: "LIVE",
+            config: configPayload.config ?? ownerConfig.config,
+            verify: verifyPayload,
+            signerRegistration,
+            heartbeat: this.heartbeatController,
+        };
+    }
+    async fetchGatewayOwnerConfig(agentId) {
+        const params = new URLSearchParams({ agentId });
+        const endpoint = `${this.merchantBaseUrl}/api/agent-gateway/config?${params.toString()}`;
+        const response = await fetch(endpoint, {
+            method: "GET",
+            headers: {
+                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            },
+            cache: "no-store",
+        });
+        const payload = await parsePayload(response);
+        if (!response.ok) {
+            const message = this.extractApiErrorMessage(payload, "Failed to load gateway owner config.");
+            throw new Error(`[activate:config_lookup] ${message}`);
+        }
+        const config = typeof payload === "object" &&
+            payload !== null &&
+            "config" in payload &&
+            typeof payload.config === "object" &&
+            payload.config !== null
+            ? (payload.config)
+            : null;
+        if (!config || !normalizeOptionalString(config.ownerAddress)) {
+            throw new Error("[activate:config_lookup] gateway config response missing ownerAddress.");
+        }
+        return {
+            configured: typeof payload === "object" && payload !== null && "configured" in payload
+                ? Boolean(payload.configured)
+                : false,
+            config,
+        };
+    }
+    async postMerchantSignedWrite(action, input) {
+        const ownerKey = assertPrivateKey(this.ownerPrivateKey, "ownerPrivateKey");
+        const ownerAddress = normalizeAddressLower(input.ownerAddress);
+        const authPayload = createMerchantGatewayAuthPayload({
+            action,
+            agentId: input.agentId,
+            ownerAddress,
+            actorAddress: ownerAddress,
+            serviceSlug: input.serviceSlug,
+        });
+        const account = privateKeyToAccount(ownerKey);
+        const authSignature = await account.signMessage({
+            message: buildMerchantGatewayAuthMessage(authPayload),
+        });
+        const endpoint = `${this.merchantBaseUrl}${input.path}`;
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            },
+            body: JSON.stringify({
+                agentId: input.agentId,
+                ownerAddress,
+                actorAddress: ownerAddress,
+                serviceSlug: input.serviceSlug,
+                authPayload,
+                authSignature,
+                ...input.body,
+            }),
+            cache: "no-store",
+        });
+        const payload = await parsePayload(response);
+        if (!response.ok) {
+            const message = this.extractApiErrorMessage(payload, `Request failed for ${action}.`);
+            throw new Error(`[activate:${action}] ${message}`);
+        }
+        return payload;
+    }
+    extractApiErrorMessage(payload, fallback) {
+        if (typeof payload === "object" && payload !== null && "error" in payload) {
+            const maybeError = payload.error;
+            if (typeof maybeError === "string" && maybeError.trim().length > 0) {
+                return maybeError.trim();
+            }
+        }
+        return fallback;
+    }
 }
 export default GhostAgent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostgate/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Ghost Protocol Node.js SDK for gate access, fulfillment, telemetry, and canary helpers.",
   "author": "Ghost Protocol",
   "license": "MIT",