@kya-os/contracts 1.3.5 → 1.4.0

package/dist/proof/proof-record.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Proof Record (Archive)
+ *
+ * Schema for proof records stored in KV/archive for audit trails
+ *
+ * Related Spec: MCP-I §5
+ * Python Reference: Edge-Delegation-Verification.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROOF_RECORD_TTL_MS = exports.ProofRecordSchema = exports.VerificationInfoSchema = exports.CrispInfoSchema = exports.LinkageInfoSchema = exports.ProofDetailsSchema = exports.ResponseInfoSchema = exports.RequestInfoSchema = void 0;
+exports.validateProofRecord = validateProofRecord;
+exports.isProofRecordExpired = isProofRecordExpired;
+const zod_1 = require("zod");
+/**
+ * Request Info Schema
+ *
+ * Information about the request that was proven
+ */
+exports.RequestInfoSchema = zod_1.z.object({
+    method: zod_1.z.string(),
+    url: zod_1.z.string().url(),
+    bodyHash: zod_1.z.string().optional(),
+    headersHash: zod_1.z.string().optional(),
+});
+/**
+ * Response Info Schema
+ *
+ * Information about the response
+ */
+exports.ResponseInfoSchema = zod_1.z.object({
+    status: zod_1.z.number().int(),
+    bodyHash: zod_1.z.string().optional(),
+});
+/**
+ * Proof Details Schema
+ *
+ * Core proof information
+ */
+exports.ProofDetailsSchema = zod_1.z.object({
+    timestamp: zod_1.z.number().int().positive(),
+    nonce: zod_1.z.string().min(1),
+    did: zod_1.z.string().min(1),
+    signature: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/),
+    algorithm: zod_1.z.enum(['Ed25519', 'ES256']),
+    sessionId: zod_1.z.string().min(1),
+    audience: zod_1.z.string().min(1),
+    request: exports.RequestInfoSchema.optional(),
+    response: exports.ResponseInfoSchema.optional(),
+});
+/**
+ * Linkage Info Schema
+ *
+ * Links to delegations and credentials
+ */
+exports.LinkageInfoSchema = zod_1.z.object({
+    delegationId: zod_1.z.string().optional(),
+    credentialId: zod_1.z.string().optional(),
+    chainDepth: zod_1.z.number().int().nonnegative().optional(),
+});
+/**
+ * CRISP Info Schema
+ *
+ * CRISP spending information
+ */
+exports.CrispInfoSchema = zod_1.z.object({
+    unit: zod_1.z.enum(['USD', 'ops', 'points']),
+    delta: zod_1.z.number().optional(),
+    remaining: zod_1.z.number().optional(),
+});
+/**
+ * Verification Info Schema
+ *
+ * Verification result for the proof
+ */
+exports.VerificationInfoSchema = zod_1.z.object({
+    result: zod_1.z.enum(['pending', 'pass', 'fail']),
+    reason: zod_1.z.string().optional(),
+    checkedAt: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Proof Record Schema
+ *
+ * Complete proof record for archive/KV storage
+ */
+exports.ProofRecordSchema = zod_1.z.object({
+    /** Unique identifier for the proof record */
+    id: zod_1.z.string().min(1),
+    /** Tool/service name that created the proof */
+    toolName: zod_1.z.string().min(1),
+    /** Timestamp when stored (milliseconds since epoch) */
+    storedAt: zod_1.z.number().int().positive(),
+    /** Expiration timestamp (milliseconds since epoch) */
+    expiresAt: zod_1.z.number().int().positive(),
+    /** Core proof details */
+    proof: exports.ProofDetailsSchema,
+    /** Optional linkage to delegations/credentials */
+    linkage: exports.LinkageInfoSchema.optional(),
+    /** Optional CRISP spending info */
+    crisp: exports.CrispInfoSchema.optional(),
+    /** Optional verification info */
+    verification: exports.VerificationInfoSchema.optional(),
+    /** Optional metadata */
+    metadata: zod_1.z.record(zod_1.z.any()).optional(),
+}).passthrough();
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a proof record
+ *
+ * @param record - The record to validate
+ * @returns Validation result
+ */
+function validateProofRecord(record) {
+    return exports.ProofRecordSchema.safeParse(record);
+}
+/**
+ * Check if proof record is expired
+ *
+ * @param record - The record to check
+ * @returns true if expired
+ */
+function isProofRecordExpired(record) {
+    return Date.now() > record.expiresAt;
+}
+/**
+ * Constants
+ */
+/**
+ * Default proof record TTL (30 days in milliseconds)
+ */
+exports.DEFAULT_PROOF_RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000;

package/dist/proof/signing-spec.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Proof Signing Specification
+ *
+ * Canonical signing order and detached JWS contracts for proofs
+ *
+ * Related Spec: MCP-I §5
+ * Python Reference: Edge-Delegation-Verification.md
+ */
+import { z } from 'zod';
+/**
+ * Canonical Request Parts Schema
+ *
+ * Parts of a request that are canonically signed
+ */
+export declare const CanonicalRequestPartsSchema: z.ZodObject<{
+    /** HTTP method (uppercased) */
+    method: z.ZodString;
+    /** Absolute URL */
+    url: z.ZodString;
+    /** Optional body hash (base64url of SHA-256) */
+    bodyHash: z.ZodOptional<z.ZodString>;
+    /** Optional headers hash (base64url of SHA-256 of allowlisted headers) */
+    headersHash: z.ZodOptional<z.ZodString>;
+    /** Nonce (base64) */
+    nonce: z.ZodString;
+    /** Timestamp (milliseconds since epoch) */
+    timestamp: z.ZodNumber;
+    /** Audience (e.g., 'mcp-client') */
+    audience: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    url: string;
+    method: string;
+    bodyHash?: string | undefined;
+    headersHash?: string | undefined;
+}, {
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    url: string;
+    method: string;
+    bodyHash?: string | undefined;
+    headersHash?: string | undefined;
+}>;
+export type CanonicalRequestParts = z.infer<typeof CanonicalRequestPartsSchema>;
+/**
+ * Detached JWS Schema
+ *
+ * Detached JSON Web Signature for proofs
+ */
+export declare const DetachedJwsSchema: z.ZodObject<{
+    /** Algorithm (Ed25519 or ES256) */
+    alg: z.ZodEnum<["Ed25519", "ES256"]>;
+    /** Optional key ID (fragment from DID) */
+    kid: z.ZodOptional<z.ZodString>;
+    /** Base64url-encoded signature */
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    alg: "Ed25519" | "ES256";
+    kid?: string | undefined;
+}, {
+    signature: string;
+    alg: "Ed25519" | "ES256";
+    kid?: string | undefined;
+}>;
+export type DetachedJws = z.infer<typeof DetachedJwsSchema>;
+/**
+ * Signing Order
+ *
+ * **CRITICAL**: This order MUST be used for canonical string generation.
+ * Changing this order breaks signature verification.
+ */
+export declare const SIGNING_ORDER: readonly ["method", "url", "bodyHash", "headersHash", "nonce", "timestamp", "audience"];
+/**
+ * Type for signing order fields
+ */
+export type SigningOrderField = (typeof SIGNING_ORDER)[number];
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate canonical request parts
+ *
+ * @param parts - The parts to validate
+ * @returns Validation result
+ */
+export declare function validateCanonicalRequestParts(parts: unknown): z.SafeParseReturnType<{
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    url: string;
+    method: string;
+    bodyHash?: string | undefined;
+    headersHash?: string | undefined;
+}, {
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    url: string;
+    method: string;
+    bodyHash?: string | undefined;
+    headersHash?: string | undefined;
+}>;
+/**
+ * Validate detached JWS
+ *
+ * @param jws - The JWS to validate
+ * @returns Validation result
+ */
+export declare function validateDetachedJws(jws: unknown): z.SafeParseReturnType<{
+    signature: string;
+    alg: "Ed25519" | "ES256";
+    kid?: string | undefined;
+}, {
+    signature: string;
+    alg: "Ed25519" | "ES256";
+    kid?: string | undefined;
+}>;
+/**
+ * Generate canonical signing string from parts
+ *
+ * **NOTE**: This is a type-level spec. Actual implementation
+ * requires runtime string concatenation.
+ *
+ * @param parts - Canonical request parts
+ * @returns Canonical string for signing
+ */
+export declare function getCanonicalSigningString(parts: CanonicalRequestParts): string;
+/**
+ * Constants
+ */
+/**
+ * Supported signing algorithms
+ */
+export declare const SUPPORTED_SIGNING_ALGORITHMS: readonly ["Ed25519", "ES256"];
+/**
+ * Hash algorithm for body/headers
+ */
+export declare const SIGNING_HASH_ALGORITHM = "SHA-256";
+/**
+ * Base64url pattern for validation
+ */
+export declare const BASE64URL_PATTERN: RegExp;

package/dist/proof/signing-spec.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Proof Signing Specification
+ *
+ * Canonical signing order and detached JWS contracts for proofs
+ *
+ * Related Spec: MCP-I §5
+ * Python Reference: Edge-Delegation-Verification.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE64URL_PATTERN = exports.SIGNING_HASH_ALGORITHM = exports.SUPPORTED_SIGNING_ALGORITHMS = exports.SIGNING_ORDER = exports.DetachedJwsSchema = exports.CanonicalRequestPartsSchema = void 0;
+exports.validateCanonicalRequestParts = validateCanonicalRequestParts;
+exports.validateDetachedJws = validateDetachedJws;
+exports.getCanonicalSigningString = getCanonicalSigningString;
+const zod_1 = require("zod");
+/**
+ * Canonical Request Parts Schema
+ *
+ * Parts of a request that are canonically signed
+ */
+exports.CanonicalRequestPartsSchema = zod_1.z.object({
+    /** HTTP method (uppercased) */
+    method: zod_1.z.string().toUpperCase(),
+    /** Absolute URL */
+    url: zod_1.z.string().url(),
+    /** Optional body hash (base64url of SHA-256) */
+    bodyHash: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/).optional(),
+    /** Optional headers hash (base64url of SHA-256 of allowlisted headers) */
+    headersHash: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/).optional(),
+    /** Nonce (base64) */
+    nonce: zod_1.z.string().min(1),
+    /** Timestamp (milliseconds since epoch) */
+    timestamp: zod_1.z.number().int().positive(),
+    /** Audience (e.g., 'mcp-client') */
+    audience: zod_1.z.string().min(1),
+});
+/**
+ * Detached JWS Schema
+ *
+ * Detached JSON Web Signature for proofs
+ */
+exports.DetachedJwsSchema = zod_1.z.object({
+    /** Algorithm (Ed25519 or ES256) */
+    alg: zod_1.z.enum(['Ed25519', 'ES256']),
+    /** Optional key ID (fragment from DID) */
+    kid: zod_1.z.string().optional(),
+    /** Base64url-encoded signature */
+    signature: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/),
+});
+/**
+ * Signing Order
+ *
+ * **CRITICAL**: This order MUST be used for canonical string generation.
+ * Changing this order breaks signature verification.
+ */
+exports.SIGNING_ORDER = Object.freeze([
+    'method',
+    'url',
+    'bodyHash',
+    'headersHash',
+    'nonce',
+    'timestamp',
+    'audience',
+]);
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate canonical request parts
+ *
+ * @param parts - The parts to validate
+ * @returns Validation result
+ */
+function validateCanonicalRequestParts(parts) {
+    return exports.CanonicalRequestPartsSchema.safeParse(parts);
+}
+/**
+ * Validate detached JWS
+ *
+ * @param jws - The JWS to validate
+ * @returns Validation result
+ */
+function validateDetachedJws(jws) {
+    return exports.DetachedJwsSchema.safeParse(jws);
+}
+/**
+ * Generate canonical signing string from parts
+ *
+ * **NOTE**: This is a type-level spec. Actual implementation
+ * requires runtime string concatenation.
+ *
+ * @param parts - Canonical request parts
+ * @returns Canonical string for signing
+ */
+function getCanonicalSigningString(parts) {
+    const values = [];
+    for (const field of exports.SIGNING_ORDER) {
+        const value = parts[field];
+        if (value !== undefined) {
+            values.push(String(value));
+        }
+        else {
+            values.push('');
+        }
+    }
+    return values.join('\n');
+}
+/**
+ * Constants
+ */
+/**
+ * Supported signing algorithms
+ */
+exports.SUPPORTED_SIGNING_ALGORITHMS = ['Ed25519', 'ES256'];
+/**
+ * Hash algorithm for body/headers
+ */
+exports.SIGNING_HASH_ALGORITHM = 'SHA-256';
+/**
+ * Base64url pattern for validation
+ */
+exports.BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;

package/dist/proof.d.ts

@@ -1,4 +1,14 @@
 import { z } from "zod";
+/**
+ * Proof and signature schemas for MCP-I
+ *
+ * Note: The type name "DetachedProof" is maintained for backward compatibility,
+ * but the JWS format is actually FULL compact JWS (header.payload.signature),
+ * not detached format (header..signature).
+ *
+ * The JWS payload contains JWT standard claims (aud, sub, iss) plus custom
+ * proof claims (requestHash, responseHash, nonce, etc.).
+ */
 export declare const ProofMetaSchema: z.ZodObject<{
     did: z.ZodString;
     kid: z.ZodString;
@@ -10,28 +20,31 @@ export declare const ProofMetaSchema: z.ZodObject<{
     responseHash: z.ZodString;
     scopeId: z.ZodOptional<z.ZodString>;
     delegationRef: z.ZodOptional<z.ZodString>;
+    clientDid: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     did: string;
     kid: string;
+    ts: number;
     nonce: string;
     audience: string;
     sessionId: string;
-    ts: number;
     requestHash: string;
     responseHash: string;
     scopeId?: string | undefined;
     delegationRef?: string | undefined;
+    clientDid?: string | undefined;
 }, {
     did: string;
     kid: string;
+    ts: number;
     nonce: string;
     audience: string;
     sessionId: string;
-    ts: number;
     requestHash: string;
     responseHash: string;
     scopeId?: string | undefined;
     delegationRef?: string | undefined;
+    clientDid?: string | undefined;
 }>;
 export declare const DetachedProofSchema: z.ZodObject<{
     jws: z.ZodString;
@@ -46,56 +59,61 @@ export declare const DetachedProofSchema: z.ZodObject<{
         responseHash: z.ZodString;
         scopeId: z.ZodOptional<z.ZodString>;
         delegationRef: z.ZodOptional<z.ZodString>;
+        clientDid: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         did: string;
         kid: string;
+        ts: number;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
         requestHash: string;
         responseHash: string;
         scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        clientDid?: string | undefined;
     }, {
         did: string;
         kid: string;
+        ts: number;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
         requestHash: string;
         responseHash: string;
         scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        clientDid?: string | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     jws: string;
     meta: {
         did: string;
         kid: string;
+        ts: number;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
         requestHash: string;
         responseHash: string;
         scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        clientDid?: string | undefined;
     };
 }, {
     jws: string;
     meta: {
         did: string;
         kid: string;
+        ts: number;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
         requestHash: string;
         responseHash: string;
         scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        clientDid?: string | undefined;
     };
 }>;
 export declare const CanonicalHashesSchema: z.ZodObject<{
@@ -120,22 +138,22 @@ export declare const AuditRecordSchema: z.ZodObject<{
     verified: z.ZodEnum<["yes", "no"]>;
     scope: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    version: "audit.v1";
     did: string;
     kid: string;
-    audience: string;
     ts: number;
+    audience: string;
+    version: "audit.v1";
     session: string;
     reqHash: string;
     resHash: string;
     verified: "yes" | "no";
     scope: string;
 }, {
-    version: "audit.v1";
     did: string;
     kid: string;
-    audience: string;
     ts: number;
+    audience: string;
+    version: "audit.v1";
     session: string;
     reqHash: string;
     resHash: string;
@@ -149,6 +167,10 @@ export type AuditRecord = z.infer<typeof AuditRecordSchema>;
 export declare const JWS_ALGORITHM = "EdDSA";
 export declare const HASH_ALGORITHM = "sha256";
 export declare const AUDIT_VERSION = "audit.v1";
+/**
+ * Tool call context for AgentShield dashboard integration
+ * Provides plaintext tool execution data alongside cryptographic proofs
+ */
 export declare const ToolCallContextSchema: z.ZodObject<{
     tool: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -168,6 +190,10 @@ export declare const ToolCallContextSchema: z.ZodObject<{
     result?: unknown;
     userId?: string | undefined;
 }>;
+/**
+ * Proof submission context for AgentShield API
+ * Includes tool calls and optional MCP server URL for tool discovery
+ */
 export declare const ProofSubmissionContextSchema: z.ZodObject<{
     toolCalls: z.ZodArray<z.ZodObject<{
         tool: z.ZodString;
@@ -208,6 +234,9 @@ export declare const ProofSubmissionContextSchema: z.ZodObject<{
     }[];
     mcpServerUrl?: string | undefined;
 }>;
+/**
+ * Complete proof submission request to AgentShield
+ */
 export declare const ProofSubmissionRequestSchema: z.ZodObject<{
     session_id: z.ZodString;
     delegation_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -224,56 +253,61 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             responseHash: z.ZodString;
             scopeId: z.ZodOptional<z.ZodString>;
             delegationRef: z.ZodOptional<z.ZodString>;
+            clientDid: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         }, {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
         jws: string;
         meta: {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         };
     }, {
         jws: string;
         meta: {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         };
     }>, "many">;
     context: z.ZodOptional<z.ZodObject<{
@@ -323,14 +357,15 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
         meta: {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;
@@ -351,14 +386,15 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
         meta: {
             did: string;
             kid: string;
+            ts: number;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
             requestHash: string;
             responseHash: string;
             scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            clientDid?: string | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;
@@ -376,3 +412,4 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
 export type ToolCallContext = z.infer<typeof ToolCallContextSchema>;
 export type ProofSubmissionContext = z.infer<typeof ProofSubmissionContextSchema>;
 export type ProofSubmissionRequest = z.infer<typeof ProofSubmissionRequestSchema>;
+//# sourceMappingURL=proof.d.ts.map