@kya-os/contracts 1.8.0 → 1.9.0

package/dist/proof.d.ts

@@ -9,6 +9,23 @@ import { z } from "zod";
  * The JWS payload contains JWT standard claims (aud, sub, iss) plus custom
  * proof claims (requestHash, responseHash, nonce, etc.).
  */
+/**
+ * Outcome of the policy decision a proof attests to (ratified DIF decision).
+ *
+ * - `allowed`             — the call was authorized and produced a response; the
+ *                           proof carries a `responseHash` over that response.
+ * - `denied`              — the call was refused; no response was produced.
+ * - `step_up_required`    — a step-up (re-auth / higher assurance) is required
+ *                           before the call may proceed; no response yet.
+ * - `needs_authorization` — explicit user authorization is required first; no
+ *                           response yet.
+ *
+ * Denial and step-up outcomes authorize no response, so their proofs omit
+ * `responseHash`. The field is optional on {@link ProofMetaSchema}: proofs minted
+ * before it existed carry no `outcome` and are treated as `allowed`.
+ */
+export declare const ProofOutcomeSchema: z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>;
+export type ProofOutcome = z.infer<typeof ProofOutcomeSchema>;
 export declare const ProofMetaSchema: z.ZodObject<{
     did: z.ZodString;
     kid: z.ZodString;
@@ -18,33 +35,36 @@ export declare const ProofMetaSchema: z.ZodObject<{
     sessionId: z.ZodString;
     requestHash: z.ZodString;
     responseHash: z.ZodString;
+    outcome: z.ZodOptional<z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>>;
     scopeId: z.ZodOptional<z.ZodString>;
     delegationRef: z.ZodOptional<z.ZodString>;
     clientDid: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    did: string;
-    kid: string;
     nonce: string;
     audience: string;
     sessionId: string;
-    ts: number;
+    did: string;
+    kid: string;
     requestHash: string;
     responseHash: string;
+    ts: number;
     clientDid?: string | undefined;
-    scopeId?: string | undefined;
     delegationRef?: string | undefined;
+    scopeId?: string | undefined;
+    outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
 }, {
-    did: string;
-    kid: string;
     nonce: string;
     audience: string;
     sessionId: string;
-    ts: number;
+    did: string;
+    kid: string;
     requestHash: string;
     responseHash: string;
+    ts: number;
     clientDid?: string | undefined;
-    scopeId?: string | undefined;
     delegationRef?: string | undefined;
+    scopeId?: string | undefined;
+    outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
 }>;
 export declare const DetachedProofSchema: z.ZodObject<{
     jws: z.ZodString;
@@ -57,63 +77,68 @@ export declare const DetachedProofSchema: z.ZodObject<{
         sessionId: z.ZodString;
         requestHash: z.ZodString;
         responseHash: z.ZodString;
+        outcome: z.ZodOptional<z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>>;
         scopeId: z.ZodOptional<z.ZodString>;
         delegationRef: z.ZodOptional<z.ZodString>;
         clientDid: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        did: string;
-        kid: string;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
+        did: string;
+        kid: string;
         requestHash: string;
         responseHash: string;
+        ts: number;
         clientDid?: string | undefined;
-        scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        scopeId?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     }, {
-        did: string;
-        kid: string;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
+        did: string;
+        kid: string;
         requestHash: string;
         responseHash: string;
+        ts: number;
         clientDid?: string | undefined;
-        scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        scopeId?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     jws: string;
     meta: {
-        did: string;
-        kid: string;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
+        did: string;
+        kid: string;
         requestHash: string;
         responseHash: string;
+        ts: number;
         clientDid?: string | undefined;
-        scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        scopeId?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     };
 }, {
     jws: string;
     meta: {
-        did: string;
-        kid: string;
         nonce: string;
         audience: string;
         sessionId: string;
-        ts: number;
+        did: string;
+        kid: string;
         requestHash: string;
         responseHash: string;
+        ts: number;
         clientDid?: string | undefined;
-        scopeId?: string | undefined;
         delegationRef?: string | undefined;
+        scopeId?: string | undefined;
+        outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     };
 }>;
 export declare const CanonicalHashesSchema: z.ZodObject<{
@@ -139,25 +164,25 @@ export declare const AuditRecordSchema: z.ZodObject<{
     scope: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     version: "audit.v1";
+    audience: string;
     did: string;
     kid: string;
-    audience: string;
-    ts: number;
     session: string;
+    verified: "yes" | "no";
+    ts: number;
     reqHash: string;
     resHash: string;
-    verified: "yes" | "no";
     scope: string;
 }, {
     version: "audit.v1";
+    audience: string;
     did: string;
     kid: string;
-    audience: string;
-    ts: number;
     session: string;
+    verified: "yes" | "no";
+    ts: number;
     reqHash: string;
     resHash: string;
-    verified: "yes" | "no";
     scope: string;
 }>;
 export type ProofMeta = z.infer<typeof ProofMetaSchema>;
@@ -181,14 +206,14 @@ export declare const ToolCallContextSchema: z.ZodObject<{
     scopeId: string;
     tool: string;
     args: Record<string, unknown>;
-    userId?: string | undefined;
     result?: unknown;
+    userId?: string | undefined;
 }, {
     scopeId: string;
     tool: string;
     args: Record<string, unknown>;
-    userId?: string | undefined;
     result?: unknown;
+    userId?: string | undefined;
 }>;
 /**
  * Proof submission context for AgentShield API
@@ -205,14 +230,14 @@ export declare const ProofSubmissionContextSchema: z.ZodObject<{
         scopeId: string;
         tool: string;
         args: Record<string, unknown>;
-        userId?: string | undefined;
         result?: unknown;
+        userId?: string | undefined;
     }, {
         scopeId: string;
         tool: string;
         args: Record<string, unknown>;
-        userId?: string | undefined;
         result?: unknown;
+        userId?: string | undefined;
     }>, "many">;
     mcpServerUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -220,8 +245,8 @@ export declare const ProofSubmissionContextSchema: z.ZodObject<{
         scopeId: string;
         tool: string;
         args: Record<string, unknown>;
-        userId?: string | undefined;
         result?: unknown;
+        userId?: string | undefined;
     }[];
     mcpServerUrl?: string | undefined;
 }, {
@@ -229,8 +254,8 @@ export declare const ProofSubmissionContextSchema: z.ZodObject<{
         scopeId: string;
         tool: string;
         args: Record<string, unknown>;
-        userId?: string | undefined;
         result?: unknown;
+        userId?: string | undefined;
     }[];
     mcpServerUrl?: string | undefined;
 }>;
@@ -251,63 +276,68 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             sessionId: z.ZodString;
             requestHash: z.ZodString;
             responseHash: z.ZodString;
+            outcome: z.ZodOptional<z.ZodEnum<["allowed", "denied", "step_up_required", "needs_authorization"]>>;
             scopeId: z.ZodOptional<z.ZodString>;
             delegationRef: z.ZodOptional<z.ZodString>;
             clientDid: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         }, {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
         jws: string;
         meta: {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         };
     }, {
         jws: string;
         meta: {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         };
     }>, "many">;
     context: z.ZodOptional<z.ZodObject<{
@@ -321,14 +351,14 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }, {
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }>, "many">;
         mcpServerUrl: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -336,8 +366,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }[];
         mcpServerUrl?: string | undefined;
     }, {
@@ -345,8 +375,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }[];
         mcpServerUrl?: string | undefined;
     }>>;
@@ -355,17 +385,18 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
     proofs: {
         jws: string;
         meta: {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;
@@ -374,8 +405,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }[];
         mcpServerUrl?: string | undefined;
     } | undefined;
@@ -384,17 +415,18 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
     proofs: {
         jws: string;
         meta: {
-            did: string;
-            kid: string;
             nonce: string;
             audience: string;
             sessionId: string;
-            ts: number;
+            did: string;
+            kid: string;
             requestHash: string;
             responseHash: string;
+            ts: number;
             clientDid?: string | undefined;
-            scopeId?: string | undefined;
             delegationRef?: string | undefined;
+            scopeId?: string | undefined;
+            outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;
@@ -403,8 +435,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: string;
             tool: string;
             args: Record<string, unknown>;
-            userId?: string | undefined;
             result?: unknown;
+            userId?: string | undefined;
         }[];
         mcpServerUrl?: string | undefined;
     } | undefined;
@@ -412,4 +444,3 @@ 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

package/dist/proof.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProofSubmissionRequestSchema = exports.ProofSubmissionContextSchema = exports.ToolCallContextSchema = exports.AUDIT_VERSION = exports.HASH_ALGORITHM = exports.JWS_ALGORITHM = exports.AuditRecordSchema = exports.CanonicalHashesSchema = exports.DetachedProofSchema = exports.ProofMetaSchema = void 0;
+exports.ProofSubmissionRequestSchema = exports.ProofSubmissionContextSchema = exports.ToolCallContextSchema = exports.AUDIT_VERSION = exports.HASH_ALGORITHM = exports.JWS_ALGORITHM = exports.AuditRecordSchema = exports.CanonicalHashesSchema = exports.DetachedProofSchema = exports.ProofMetaSchema = exports.ProofOutcomeSchema = void 0;
 const zod_1 = require("zod");
 /**
  * Proof and signature schemas for MCP-I
@@ -12,6 +12,27 @@ const zod_1 = require("zod");
  * The JWS payload contains JWT standard claims (aud, sub, iss) plus custom
  * proof claims (requestHash, responseHash, nonce, etc.).
  */
+/**
+ * Outcome of the policy decision a proof attests to (ratified DIF decision).
+ *
+ * - `allowed`             — the call was authorized and produced a response; the
+ *                           proof carries a `responseHash` over that response.
+ * - `denied`              — the call was refused; no response was produced.
+ * - `step_up_required`    — a step-up (re-auth / higher assurance) is required
+ *                           before the call may proceed; no response yet.
+ * - `needs_authorization` — explicit user authorization is required first; no
+ *                           response yet.
+ *
+ * Denial and step-up outcomes authorize no response, so their proofs omit
+ * `responseHash`. The field is optional on {@link ProofMetaSchema}: proofs minted
+ * before it existed carry no `outcome` and are treated as `allowed`.
+ */
+exports.ProofOutcomeSchema = zod_1.z.enum([
+    "allowed",
+    "denied",
+    "step_up_required",
+    "needs_authorization",
+]);
 exports.ProofMetaSchema = zod_1.z.object({
     did: zod_1.z.string().min(1),
     kid: zod_1.z.string().min(1),
@@ -21,6 +42,13 @@ exports.ProofMetaSchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),
     requestHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
     responseHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    // Policy outcome this proof attests to (ratified DIF decision); absent on
+    // legacy proofs, which consumers treat as "allowed". Per the ratified schema
+    // `responseHash` is present only for the "allowed" outcome — the verifier
+    // enforces that outcome-conditionally. `responseHash` stays required-typed
+    // here to avoid a repo-wide `string | undefined` ripple; making it
+    // conditionally optional is a deferred schema refinement.
+    outcome: exports.ProofOutcomeSchema.optional(),
     scopeId: zod_1.z.string().optional(),
     delegationRef: zod_1.z.string().optional(),
     clientDid: zod_1.z.string().optional(), // Optional for backward compatibility
@@ -80,4 +108,3 @@ exports.ProofSubmissionRequestSchema = zod_1.z.object({
     })),
     context: exports.ProofSubmissionContextSchema.optional(),
 });
-//# sourceMappingURL=proof.js.map

package/dist/runtime/headers.d.ts

@@ -13,31 +13,34 @@
  */
 export interface DownstreamHeaders {
     /** DID of the verified agent */
-    'KYA-Agent-DID': string;
-    /** Optional delegation ID */
-    'KYA-Delegation-Id'?: string;
+    'KYA-OS-Agent-DID': string;
     /** Optional delegation chain (format: vc_id>del_id>...) */
-    'KYA-Delegation-Chain'?: string;
+    'KYA-OS-Delegation-Chain'?: string;
+    /** Optional Layer 2 delegation proof (signed JWT) */
+    'KYA-OS-Delegation-Proof'?: string;
+    /** Optional JWS-compact DelegationCredential VC */
+    'KYA-OS-Delegation-Credential'?: string;
     /** Proof ID for audit trail */
     'KYA-Proof-Id': string;
     /** Optional CRISP spend info (JSON string: {unit, delta, remaining}) */
     'KYA-CRISP-Spend'?: string;
     /** Optional session ID */
-    'KYA-Session-Id'?: string;
+    'KYA-OS-Session-Id'?: string;
     /** Optional scopes */
-    'KYA-Granted-Scopes'?: string;
+    'KYA-OS-Granted-Scopes'?: string;
 }
 /**
  * Header names as constants for type safety
  */
 export declare const DOWNSTREAM_HEADER_NAMES: Readonly<{
-    readonly AGENT_DID: "KYA-Agent-DID";
-    readonly DELEGATION_ID: "KYA-Delegation-Id";
-    readonly DELEGATION_CHAIN: "KYA-Delegation-Chain";
+    readonly AGENT_DID: "KYA-OS-Agent-DID";
+    readonly DELEGATION_CHAIN: "KYA-OS-Delegation-Chain";
+    readonly DELEGATION_PROOF: "KYA-OS-Delegation-Proof";
+    readonly DELEGATION_CREDENTIAL: "KYA-OS-Delegation-Credential";
     readonly PROOF_ID: "KYA-Proof-Id";
     readonly CRISP_SPEND: "KYA-CRISP-Spend";
-    readonly SESSION_ID: "KYA-Session-Id";
-    readonly SCOPES: "KYA-Granted-Scopes";
+    readonly SESSION_ID: "KYA-OS-Session-Id";
+    readonly SCOPES: "KYA-OS-Granted-Scopes";
 }>;
 /**
  * CRISP Spend Info
@@ -75,8 +78,9 @@ export declare function parseCrispSpend(headerValue: string): CrispSpendInfo | n
 export declare function createDownstreamHeaders(config: {
     agentDid: string;
     proofId: string;
-    delegationId?: string;
     delegationChain?: string;
+    delegationProof?: string;
+    delegationCredential?: string;
     crispSpend?: CrispSpendInfo;
     sessionId?: string;
     scopes?: string[];

package/dist/runtime/headers.js

@@ -16,13 +16,14 @@ exports.createDownstreamHeaders = createDownstreamHeaders;
  * Header names as constants for type safety
  */
 exports.DOWNSTREAM_HEADER_NAMES = Object.freeze({
-    AGENT_DID: 'KYA-Agent-DID',
-    DELEGATION_ID: 'KYA-Delegation-Id',
-    DELEGATION_CHAIN: 'KYA-Delegation-Chain',
+    AGENT_DID: 'KYA-OS-Agent-DID',
+    DELEGATION_CHAIN: 'KYA-OS-Delegation-Chain',
+    DELEGATION_PROOF: 'KYA-OS-Delegation-Proof',
+    DELEGATION_CREDENTIAL: 'KYA-OS-Delegation-Credential',
     PROOF_ID: 'KYA-Proof-Id',
     CRISP_SPEND: 'KYA-CRISP-Spend',
-    SESSION_ID: 'KYA-Session-Id',
-    SCOPES: 'KYA-Granted-Scopes',
+    SESSION_ID: 'KYA-OS-Session-Id',
+    SCOPES: 'KYA-OS-Granted-Scopes',
 });
 /**
  * Helper to serialize CRISP spend info to header value
@@ -59,23 +60,26 @@ function parseCrispSpend(headerValue) {
  */
 function createDownstreamHeaders(config) {
     const headers = {
-        'KYA-Agent-DID': config.agentDid,
+        'KYA-OS-Agent-DID': config.agentDid,
         'KYA-Proof-Id': config.proofId,
     };
-    if (config.delegationId) {
-        headers['KYA-Delegation-Id'] = config.delegationId;
-    }
     if (config.delegationChain) {
-        headers['KYA-Delegation-Chain'] = config.delegationChain;
+        headers['KYA-OS-Delegation-Chain'] = config.delegationChain;
+    }
+    if (config.delegationProof) {
+        headers['KYA-OS-Delegation-Proof'] = config.delegationProof;
+    }
+    if (config.delegationCredential) {
+        headers['KYA-OS-Delegation-Credential'] = config.delegationCredential;
     }
     if (config.crispSpend) {
         headers['KYA-CRISP-Spend'] = serializeCrispSpend(config.crispSpend);
     }
     if (config.sessionId) {
-        headers['KYA-Session-Id'] = config.sessionId;
+        headers['KYA-OS-Session-Id'] = config.sessionId;
     }
     if (config.scopes && config.scopes.length > 0) {
-        headers['KYA-Granted-Scopes'] = config.scopes.join(',');
+        headers['KYA-OS-Granted-Scopes'] = config.scopes.join(',');
     }
     return headers;
 }