@paypol-protocol/aps-1 1.0.0

package/dist/validator.d.ts

@@ -0,0 +1,534 @@
+/**
+ * APS-1 Validator
+ *
+ * Runtime validation schemas for APS-1 protocol messages.
+ * Uses Zod for type-safe validation of manifests, execution envelopes, and results.
+ */
+import { z } from 'zod';
+export declare const APS1ManifestSchema: z.ZodObject<{
+    aps: z.ZodLiteral<"1.0">;
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<["security", "escrow", "payments", "streams", "analytics", "deployment", "privacy", "verification", "orchestration", "payroll", "admin"]>;
+    version: z.ZodString;
+    pricing: z.ZodObject<{
+        basePrice: z.ZodNumber;
+        currency: z.ZodLiteral<"USD">;
+        negotiable: z.ZodBoolean;
+        minPrice: z.ZodOptional<z.ZodNumber>;
+        maxPrice: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        currency: "USD";
+        basePrice: number;
+        negotiable: boolean;
+        minPrice?: number | undefined;
+        maxPrice?: number | undefined;
+    }, {
+        currency: "USD";
+        basePrice: number;
+        negotiable: boolean;
+        minPrice?: number | undefined;
+        maxPrice?: number | undefined;
+    }>;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    paymentMethods: z.ZodArray<z.ZodEnum<["nexus-escrow", "stream-milestone", "direct-transfer"]>, "many">;
+    supportedTokens: z.ZodArray<z.ZodObject<{
+        symbol: z.ZodString;
+        address: z.ZodString;
+        decimals: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        symbol: string;
+        address: string;
+        decimals: number;
+    }, {
+        symbol: string;
+        address: string;
+        decimals: number;
+    }>, "many">;
+    proofEnabled: z.ZodBoolean;
+    reputationScore: z.ZodOptional<z.ZodNumber>;
+    walletAddress: z.ZodString;
+    endpoints: z.ZodObject<{
+        manifest: z.ZodString;
+        execute: z.ZodString;
+        negotiate: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        health: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        manifest: string;
+        execute: string;
+        status?: string | undefined;
+        negotiate?: string | undefined;
+        health?: string | undefined;
+    }, {
+        manifest: string;
+        execute: string;
+        status?: string | undefined;
+        negotiate?: string | undefined;
+        health?: string | undefined;
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    description: string;
+    version: string;
+    aps: "1.0";
+    category: "streams" | "security" | "escrow" | "payments" | "analytics" | "deployment" | "privacy" | "verification" | "orchestration" | "payroll" | "admin";
+    pricing: {
+        currency: "USD";
+        basePrice: number;
+        negotiable: boolean;
+        minPrice?: number | undefined;
+        maxPrice?: number | undefined;
+    };
+    capabilities: string[];
+    paymentMethods: ("nexus-escrow" | "stream-milestone" | "direct-transfer")[];
+    supportedTokens: {
+        symbol: string;
+        address: string;
+        decimals: number;
+    }[];
+    proofEnabled: boolean;
+    walletAddress: string;
+    endpoints: {
+        manifest: string;
+        execute: string;
+        status?: string | undefined;
+        negotiate?: string | undefined;
+        health?: string | undefined;
+    };
+    metadata?: Record<string, unknown> | undefined;
+    reputationScore?: number | undefined;
+}, {
+    name: string;
+    id: string;
+    description: string;
+    version: string;
+    aps: "1.0";
+    category: "streams" | "security" | "escrow" | "payments" | "analytics" | "deployment" | "privacy" | "verification" | "orchestration" | "payroll" | "admin";
+    pricing: {
+        currency: "USD";
+        basePrice: number;
+        negotiable: boolean;
+        minPrice?: number | undefined;
+        maxPrice?: number | undefined;
+    };
+    capabilities: string[];
+    paymentMethods: ("nexus-escrow" | "stream-milestone" | "direct-transfer")[];
+    supportedTokens: {
+        symbol: string;
+        address: string;
+        decimals: number;
+    }[];
+    proofEnabled: boolean;
+    walletAddress: string;
+    endpoints: {
+        manifest: string;
+        execute: string;
+        status?: string | undefined;
+        negotiate?: string | undefined;
+        health?: string | undefined;
+    };
+    metadata?: Record<string, unknown> | undefined;
+    reputationScore?: number | undefined;
+}>;
+export declare const APS1NegotiationSchema: z.ZodObject<{
+    type: z.ZodEnum<["propose", "counter", "accept", "reject"]>;
+    jobId: z.ZodString;
+    price: z.ZodNumber;
+    currency: z.ZodLiteral<"USD">;
+    message: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    currency: "USD";
+    type: "accept" | "reject" | "propose" | "counter";
+    timestamp: string;
+    jobId: string;
+    price: number;
+    message?: string | undefined;
+}, {
+    currency: "USD";
+    type: "accept" | "reject" | "propose" | "counter";
+    timestamp: string;
+    jobId: string;
+    price: number;
+    message?: string | undefined;
+}>;
+export declare const APS1EscrowParamsSchema: z.ZodObject<{
+    method: z.ZodEnum<["nexus-escrow", "stream-milestone", "direct-transfer"]>;
+    token: z.ZodString;
+    amount: z.ZodString;
+    amountUSD: z.ZodNumber;
+    deadlineSeconds: z.ZodNumber;
+    workerWallet: z.ZodString;
+    judgeWallet: z.ZodOptional<z.ZodString>;
+    milestones: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodString;
+        deliverable: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        deliverable: string;
+    }, {
+        amount: string;
+        deliverable: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+    token: string;
+    amount: string;
+    amountUSD: number;
+    deadlineSeconds: number;
+    workerWallet: string;
+    judgeWallet?: string | undefined;
+    milestones?: {
+        amount: string;
+        deliverable: string;
+    }[] | undefined;
+}, {
+    method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+    token: string;
+    amount: string;
+    amountUSD: number;
+    deadlineSeconds: number;
+    workerWallet: string;
+    judgeWallet?: string | undefined;
+    milestones?: {
+        amount: string;
+        deliverable: string;
+    }[] | undefined;
+}>;
+export declare const APS1ExecutionEnvelopeSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    agentId: z.ZodString;
+    prompt: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    callerWallet: z.ZodString;
+    escrow: z.ZodOptional<z.ZodObject<{
+        contractAddress: z.ZodString;
+        onChainId: z.ZodNumber;
+        txHash: z.ZodString;
+        method: z.ZodEnum<["nexus-escrow", "stream-milestone", "direct-transfer"]>;
+    }, "strip", z.ZodTypeAny, {
+        method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+        contractAddress: string;
+        onChainId: number;
+        txHash: string;
+    }, {
+        method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+        contractAddress: string;
+        onChainId: number;
+        txHash: string;
+    }>>;
+    proof: z.ZodOptional<z.ZodObject<{
+        planHash: z.ZodString;
+        commitmentId: z.ZodString;
+        commitTxHash: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        planHash: string;
+        commitmentId: string;
+        commitTxHash: string;
+    }, {
+        planHash: string;
+        commitmentId: string;
+        commitTxHash: string;
+    }>>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    prompt: string;
+    jobId: string;
+    agentId: string;
+    callerWallet: string;
+    escrow?: {
+        method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+        contractAddress: string;
+        onChainId: number;
+        txHash: string;
+    } | undefined;
+    proof?: {
+        planHash: string;
+        commitmentId: string;
+        commitTxHash: string;
+    } | undefined;
+    payload?: Record<string, unknown> | undefined;
+}, {
+    timestamp: string;
+    prompt: string;
+    jobId: string;
+    agentId: string;
+    callerWallet: string;
+    escrow?: {
+        method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+        contractAddress: string;
+        onChainId: number;
+        txHash: string;
+    } | undefined;
+    proof?: {
+        planHash: string;
+        commitmentId: string;
+        commitTxHash: string;
+    } | undefined;
+    payload?: Record<string, unknown> | undefined;
+}>;
+export declare const APS1ResultSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    agentId: z.ZodString;
+    status: z.ZodEnum<["success", "error", "pending"]>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+    onChain: z.ZodOptional<z.ZodObject<{
+        executed: z.ZodBoolean;
+        transactions: z.ZodArray<z.ZodObject<{
+            hash: z.ZodString;
+            blockNumber: z.ZodNumber;
+            gasUsed: z.ZodString;
+            explorerUrl: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }, {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }>, "many">;
+        network: z.ZodString;
+        chainId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        network: string;
+        executed: boolean;
+        chainId: number;
+        transactions: {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }[];
+    }, {
+        network: string;
+        executed: boolean;
+        chainId: number;
+        transactions: {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }[];
+    }>>;
+    proof: z.ZodOptional<z.ZodObject<{
+        resultHash: z.ZodString;
+        verifyTxHash: z.ZodString;
+        matched: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        resultHash: string;
+        verifyTxHash: string;
+        matched: boolean;
+    }, {
+        resultHash: string;
+        verifyTxHash: string;
+        matched: boolean;
+    }>>;
+    executionTimeMs: z.ZodNumber;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    status: "error" | "pending" | "success";
+    jobId: string;
+    agentId: string;
+    executionTimeMs: number;
+    error?: string | undefined;
+    result?: unknown;
+    onChain?: {
+        network: string;
+        executed: boolean;
+        chainId: number;
+        transactions: {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+    proof?: {
+        resultHash: string;
+        verifyTxHash: string;
+        matched: boolean;
+    } | undefined;
+}, {
+    timestamp: string;
+    status: "error" | "pending" | "success";
+    jobId: string;
+    agentId: string;
+    executionTimeMs: number;
+    error?: string | undefined;
+    result?: unknown;
+    onChain?: {
+        network: string;
+        executed: boolean;
+        chainId: number;
+        transactions: {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+    proof?: {
+        resultHash: string;
+        verifyTxHash: string;
+        matched: boolean;
+    } | undefined;
+}>;
+export declare const APS1SettlementSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    type: z.ZodEnum<["settle", "refund", "dispute"]>;
+    agentPayout: z.ZodString;
+    platformFee: z.ZodString;
+    txHash: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "settle" | "refund" | "dispute";
+    timestamp: string;
+    jobId: string;
+    txHash: string;
+    agentPayout: string;
+    platformFee: string;
+}, {
+    type: "settle" | "refund" | "dispute";
+    timestamp: string;
+    jobId: string;
+    txHash: string;
+    agentPayout: string;
+    platformFee: string;
+}>;
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: string[];
+};
+/** Validate an APS-1 agent manifest */
+export declare function validateManifest(data: unknown): ValidationResult<{
+    name: string;
+    id: string;
+    description: string;
+    version: string;
+    aps: "1.0";
+    category: "streams" | "security" | "escrow" | "payments" | "analytics" | "deployment" | "privacy" | "verification" | "orchestration" | "payroll" | "admin";
+    pricing: {
+        currency: "USD";
+        basePrice: number;
+        negotiable: boolean;
+        minPrice?: number | undefined;
+        maxPrice?: number | undefined;
+    };
+    capabilities: string[];
+    paymentMethods: ("nexus-escrow" | "stream-milestone" | "direct-transfer")[];
+    supportedTokens: {
+        symbol: string;
+        address: string;
+        decimals: number;
+    }[];
+    proofEnabled: boolean;
+    walletAddress: string;
+    endpoints: {
+        manifest: string;
+        execute: string;
+        status?: string | undefined;
+        negotiate?: string | undefined;
+        health?: string | undefined;
+    };
+    metadata?: Record<string, unknown> | undefined;
+    reputationScore?: number | undefined;
+}>;
+/** Validate an APS-1 execution envelope */
+export declare function validateEnvelope(data: unknown): ValidationResult<{
+    timestamp: string;
+    prompt: string;
+    jobId: string;
+    agentId: string;
+    callerWallet: string;
+    escrow?: {
+        method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+        contractAddress: string;
+        onChainId: number;
+        txHash: string;
+    } | undefined;
+    proof?: {
+        planHash: string;
+        commitmentId: string;
+        commitTxHash: string;
+    } | undefined;
+    payload?: Record<string, unknown> | undefined;
+}>;
+/** Validate an APS-1 execution result */
+export declare function validateResult(data: unknown): ValidationResult<{
+    timestamp: string;
+    status: "error" | "pending" | "success";
+    jobId: string;
+    agentId: string;
+    executionTimeMs: number;
+    error?: string | undefined;
+    result?: unknown;
+    onChain?: {
+        network: string;
+        executed: boolean;
+        chainId: number;
+        transactions: {
+            hash: string;
+            blockNumber: number;
+            gasUsed: string;
+            explorerUrl: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+    proof?: {
+        resultHash: string;
+        verifyTxHash: string;
+        matched: boolean;
+    } | undefined;
+}>;
+/** Validate APS-1 escrow parameters */
+export declare function validateEscrowParams(data: unknown): ValidationResult<{
+    method: "nexus-escrow" | "stream-milestone" | "direct-transfer";
+    token: string;
+    amount: string;
+    amountUSD: number;
+    deadlineSeconds: number;
+    workerWallet: string;
+    judgeWallet?: string | undefined;
+    milestones?: {
+        amount: string;
+        deliverable: string;
+    }[] | undefined;
+}>;
+/** Validate an APS-1 negotiation message */
+export declare function validateNegotiation(data: unknown): ValidationResult<{
+    currency: "USD";
+    type: "accept" | "reject" | "propose" | "counter";
+    timestamp: string;
+    jobId: string;
+    price: number;
+    message?: string | undefined;
+}>;
+/** Validate an APS-1 settlement event */
+export declare function validateSettlement(data: unknown): ValidationResult<{
+    type: "settle" | "refund" | "dispute";
+    timestamp: string;
+    jobId: string;
+    txHash: string;
+    agentPayout: string;
+    platformFee: string;
+}>;

package/dist/validator.js

@@ -0,0 +1,164 @@
+/**
+ * APS-1 Validator
+ *
+ * Runtime validation schemas for APS-1 protocol messages.
+ * Uses Zod for type-safe validation of manifests, execution envelopes, and results.
+ */
+import { z } from 'zod';
+// ── Shared Schemas ─────────────────────────────────────────
+const ethAddress = z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address');
+const bytes32 = z.string().regex(/^0x[a-fA-F0-9]{64}$/, 'Invalid bytes32 hash');
+const isoTimestamp = z.string().datetime({ message: 'Must be ISO 8601 timestamp' });
+const categorySchema = z.enum([
+    'security', 'escrow', 'payments', 'streams', 'analytics',
+    'deployment', 'privacy', 'verification', 'orchestration', 'payroll', 'admin',
+]);
+const paymentMethodSchema = z.enum(['nexus-escrow', 'stream-milestone', 'direct-transfer']);
+const tokenConfigSchema = z.object({
+    symbol: z.string().min(1).max(20),
+    address: ethAddress,
+    decimals: z.number().int().min(0).max(18),
+});
+// ── APS-1 Manifest Schema ──────────────────────────────────
+export const APS1ManifestSchema = z.object({
+    aps: z.literal('1.0'),
+    id: z.string().min(1).max(64).regex(/^[a-z0-9-]+$/, 'Must be kebab-case'),
+    name: z.string().min(1).max(128),
+    description: z.string().min(1).max(1024),
+    category: categorySchema,
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semver (e.g. 1.0.0)'),
+    pricing: z.object({
+        basePrice: z.number().min(0),
+        currency: z.literal('USD'),
+        negotiable: z.boolean(),
+        minPrice: z.number().min(0).optional(),
+        maxPrice: z.number().min(0).optional(),
+    }),
+    capabilities: z.array(z.string()).min(1),
+    paymentMethods: z.array(paymentMethodSchema).min(1),
+    supportedTokens: z.array(tokenConfigSchema).min(1),
+    proofEnabled: z.boolean(),
+    reputationScore: z.number().int().min(0).max(10000).optional(),
+    walletAddress: ethAddress,
+    endpoints: z.object({
+        manifest: z.string().url(),
+        execute: z.string().url(),
+        negotiate: z.string().url().optional(),
+        status: z.string().url().optional(),
+        health: z.string().url().optional(),
+    }),
+    metadata: z.record(z.unknown()).optional(),
+});
+// ── APS-1 Negotiation Message Schema ───────────────────────
+export const APS1NegotiationSchema = z.object({
+    type: z.enum(['propose', 'counter', 'accept', 'reject']),
+    jobId: z.string().min(1),
+    price: z.number().min(0),
+    currency: z.literal('USD'),
+    message: z.string().max(1024).optional(),
+    timestamp: isoTimestamp,
+});
+// ── APS-1 Escrow Params Schema ─────────────────────────────
+export const APS1EscrowParamsSchema = z.object({
+    method: paymentMethodSchema,
+    token: ethAddress,
+    amount: z.string().min(1),
+    amountUSD: z.number().min(0),
+    deadlineSeconds: z.number().int().min(60).max(30 * 24 * 3600), // 1 min to 30 days
+    workerWallet: ethAddress,
+    judgeWallet: ethAddress.optional(),
+    milestones: z.array(z.object({
+        amount: z.string().min(1),
+        deliverable: z.string().min(1).max(512),
+    })).optional(),
+});
+// ── APS-1 Execution Envelope Schema ────────────────────────
+export const APS1ExecutionEnvelopeSchema = z.object({
+    jobId: z.string().min(1),
+    agentId: z.string().min(1),
+    prompt: z.string().min(1).max(10000),
+    payload: z.record(z.unknown()).optional(),
+    callerWallet: ethAddress,
+    escrow: z.object({
+        contractAddress: ethAddress,
+        onChainId: z.number().int().min(0),
+        txHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+        method: paymentMethodSchema,
+    }).optional(),
+    proof: z.object({
+        planHash: bytes32,
+        commitmentId: bytes32,
+        commitTxHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+    }).optional(),
+    timestamp: isoTimestamp,
+});
+// ── APS-1 Result Schema ────────────────────────────────────
+export const APS1ResultSchema = z.object({
+    jobId: z.string().min(1),
+    agentId: z.string().min(1),
+    status: z.enum(['success', 'error', 'pending']),
+    result: z.unknown().optional(),
+    error: z.string().optional(),
+    onChain: z.object({
+        executed: z.boolean(),
+        transactions: z.array(z.object({
+            hash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+            blockNumber: z.number().int().min(0),
+            gasUsed: z.string(),
+            explorerUrl: z.string().url(),
+            description: z.string().optional(),
+        })),
+        network: z.string(),
+        chainId: z.number().int(),
+    }).optional(),
+    proof: z.object({
+        resultHash: bytes32,
+        verifyTxHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+        matched: z.boolean(),
+    }).optional(),
+    executionTimeMs: z.number().int().min(0),
+    timestamp: isoTimestamp,
+});
+// ── APS-1 Settlement Schema ────────────────────────────────
+export const APS1SettlementSchema = z.object({
+    jobId: z.string().min(1),
+    type: z.enum(['settle', 'refund', 'dispute']),
+    agentPayout: z.string(),
+    platformFee: z.string(),
+    txHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+    timestamp: isoTimestamp,
+});
+function validate(schema, data) {
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`),
+    };
+}
+/** Validate an APS-1 agent manifest */
+export function validateManifest(data) {
+    return validate(APS1ManifestSchema, data);
+}
+/** Validate an APS-1 execution envelope */
+export function validateEnvelope(data) {
+    return validate(APS1ExecutionEnvelopeSchema, data);
+}
+/** Validate an APS-1 execution result */
+export function validateResult(data) {
+    return validate(APS1ResultSchema, data);
+}
+/** Validate APS-1 escrow parameters */
+export function validateEscrowParams(data) {
+    return validate(APS1EscrowParamsSchema, data);
+}
+/** Validate an APS-1 negotiation message */
+export function validateNegotiation(data) {
+    return validate(APS1NegotiationSchema, data);
+}
+/** Validate an APS-1 settlement event */
+export function validateSettlement(data) {
+    return validate(APS1SettlementSchema, data);
+}