@kya-os/contracts 1.3.5 → 1.4.0

package/dist/proof.js

@@ -2,6 +2,16 @@
 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;
 const zod_1 = require("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.).
+ */
 exports.ProofMetaSchema = zod_1.z.object({
     did: zod_1.z.string().min(1),
     kid: zod_1.z.string().min(1),
@@ -13,10 +23,11 @@ exports.ProofMetaSchema = zod_1.z.object({
     responseHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
     scopeId: zod_1.z.string().optional(),
     delegationRef: zod_1.z.string().optional(),
+    clientDid: zod_1.z.string().optional(), // Optional for backward compatibility
 });
 exports.DetachedProofSchema = zod_1.z.object({
-    jws: zod_1.z.string().min(1),
-    meta: exports.ProofMetaSchema,
+    jws: zod_1.z.string().min(1), // Full compact JWS format (header.payload.signature)
+    meta: exports.ProofMetaSchema, // Convenience metadata (duplicates signed payload data)
 });
 exports.CanonicalHashesSchema = zod_1.z.object({
     requestHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
@@ -32,11 +43,16 @@ exports.AuditRecordSchema = zod_1.z.object({
     reqHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
     resHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
     verified: zod_1.z.enum(["yes", "no"]),
-    scope: zod_1.z.string().min(1),
+    scope: zod_1.z.string().min(1), // "-" for no scope
 });
+// Constants
 exports.JWS_ALGORITHM = "EdDSA";
 exports.HASH_ALGORITHM = "sha256";
 exports.AUDIT_VERSION = "audit.v1";
+/**
+ * Tool call context for AgentShield dashboard integration
+ * Provides plaintext tool execution data alongside cryptographic proofs
+ */
 exports.ToolCallContextSchema = zod_1.z.object({
     tool: zod_1.z.string().min(1),
     args: zod_1.z.record(zod_1.z.unknown()),
@@ -44,10 +60,17 @@ exports.ToolCallContextSchema = zod_1.z.object({
     scopeId: zod_1.z.string(),
     userId: zod_1.z.string().optional(),
 });
+/**
+ * Proof submission context for AgentShield API
+ * Includes tool calls and optional MCP server URL for tool discovery
+ */
 exports.ProofSubmissionContextSchema = zod_1.z.object({
     toolCalls: zod_1.z.array(exports.ToolCallContextSchema),
     mcpServerUrl: zod_1.z.string().url().optional(),
 });
+/**
+ * Complete proof submission request to AgentShield
+ */
 exports.ProofSubmissionRequestSchema = zod_1.z.object({
     session_id: zod_1.z.string().min(1),
     delegation_id: zod_1.z.string().nullable().optional(),
@@ -57,3 +80,4 @@ exports.ProofSubmissionRequestSchema = zod_1.z.object({
     })),
     context: exports.ProofSubmissionContextSchema.optional(),
 });
+//# sourceMappingURL=proof.js.map

package/dist/registry.d.ts

@@ -1,4 +1,7 @@
 import { z } from "zod";
+/**
+ * Registry integration schemas (Know-That-AI and MCP Registry)
+ */
 export declare const RegistrationInputSchema: z.ZodObject<{
     agentDID: z.ZodString;
     agentURL: z.ZodString;
@@ -122,6 +125,9 @@ export declare const AgentStatusSchema: z.ZodObject<{
     };
     lastHandshake?: number | undefined;
 }>;
+/**
+ * Delegation schemas for verifiable credentials
+ */
 export declare const DelegationSchema: z.ZodObject<{
     issuer: z.ZodString;
     subject: z.ZodString;
@@ -163,7 +169,14 @@ export declare const DelegationRequestSchema: z.ZodObject<{
     audience?: string | undefined;
     duration?: number | undefined;
 }>;
+/**
+ * Storage mode configuration for verifiable credentials and delegations
+ */
 export declare const StorageModeSchema: z.ZodEnum<["ktaEncrypted", "hybridReceiptsOnly", "selfHostedAuthoritative"]>;
+/**
+ * Receipt object returned by KTA for verifiable operations
+ * Schema ID: https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json
+ */
 export declare const ReceiptSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodLiteral<"https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json">>;
     ref: z.ZodString;
@@ -290,6 +303,9 @@ export declare const DelegationResponseSchema: z.ZodObject<{
     };
     encryptedPayload?: string | undefined;
 }>;
+/**
+ * Storage configuration for different deployment modes
+ */
 export declare const StorageConfigSchema: z.ZodObject<{
     mode: z.ZodEnum<["ktaEncrypted", "hybridReceiptsOnly", "selfHostedAuthoritative"]>;
     encryptionEnabled: z.ZodDefault<z.ZodBoolean>;

package/dist/registry.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONTENT_HASH_REGEX = exports.RECEIPT_SCHEMA_ID = exports.STORAGE_MODE_ENV_VAR = exports.DEFAULT_STORAGE_MODE = exports.KTA_BASE_URL = exports.CLAIM_TOKEN_TTL_HOURS = exports.MCP_I_CAPABILITIES = exports.StorageConfigSchema = exports.DelegationResponseSchema = exports.ReceiptSchema = exports.StorageModeSchema = exports.DelegationRequestSchema = exports.DelegationSchema = exports.AgentStatusSchema = exports.MirrorStatusSchema = exports.ClaimTokenSchema = exports.RegistrationResultSchema = exports.RegistrationInputSchema = void 0;
 const zod_1 = require("zod");
+/**
+ * Registry integration schemas (Know-That-AI and MCP Registry)
+ */
 exports.RegistrationInputSchema = zod_1.z.object({
     agentDID: zod_1.z.string().min(1),
     agentURL: zod_1.z.string().url(),
@@ -42,26 +45,36 @@ exports.AgentStatusSchema = zod_1.z.object({
     mirrorStatus: exports.MirrorStatusSchema,
     lastHandshake: zod_1.z.number().int().positive().optional(),
 });
+/**
+ * Delegation schemas for verifiable credentials
+ */
 exports.DelegationSchema = zod_1.z.object({
-    issuer: zod_1.z.string().min(1),
-    subject: zod_1.z.string().min(1),
+    issuer: zod_1.z.string().min(1), // DID of the issuer
+    subject: zod_1.z.string().min(1), // DID of the subject
     scopes: zod_1.z.array(zod_1.z.string()),
-    nbf: zod_1.z.number().int().positive(),
-    exp: zod_1.z.number().int().positive(),
-    aud: zod_1.z.string().optional(),
-    delegationRef: zod_1.z.string().optional(),
+    nbf: zod_1.z.number().int().positive(), // Not before (unix timestamp)
+    exp: zod_1.z.number().int().positive(), // Expires (unix timestamp)
+    aud: zod_1.z.string().optional(), // Audience (optional)
+    delegationRef: zod_1.z.string().optional(), // Reference to parent delegation
 });
 exports.DelegationRequestSchema = zod_1.z.object({
     subject: zod_1.z.string().min(1),
     scopes: zod_1.z.array(zod_1.z.string()),
-    duration: zod_1.z.number().int().positive().optional(),
+    duration: zod_1.z.number().int().positive().optional(), // Duration in seconds
     audience: zod_1.z.string().optional(),
 });
+/**
+ * Storage mode configuration for verifiable credentials and delegations
+ */
 exports.StorageModeSchema = zod_1.z.enum([
     "ktaEncrypted",
     "hybridReceiptsOnly",
     "selfHostedAuthoritative",
 ]);
+/**
+ * Receipt object returned by KTA for verifiable operations
+ * Schema ID: https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json
+ */
 exports.ReceiptSchema = zod_1.z.object({
     $schema: zod_1.z
         .literal("https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json")
@@ -69,6 +82,7 @@ exports.ReceiptSchema = zod_1.z.object({
     ref: zod_1.z.string().min(1),
     contentHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
     action: zod_1.z.enum(["issue", "revoke"]),
+    // Back-compat: accept ISO string (preferred) or legacy epoch number
     ts: zod_1.z.union([zod_1.z.string().datetime(), zod_1.z.number().int().positive()]),
     logIndex: zod_1.z.number().int().nonnegative(),
     logRoot: zod_1.z.string().min(1),
@@ -77,22 +91,28 @@ exports.ReceiptSchema = zod_1.z.object({
 exports.DelegationResponseSchema = zod_1.z.object({
     delegation: exports.DelegationSchema,
     receipt: exports.ReceiptSchema,
-    encryptedPayload: zod_1.z.string().optional(),
+    encryptedPayload: zod_1.z.string().optional(), // For ktaEncrypted mode
 });
+/**
+ * Storage configuration for different deployment modes
+ */
 exports.StorageConfigSchema = zod_1.z.object({
     mode: exports.StorageModeSchema,
     encryptionEnabled: zod_1.z.boolean().default(false),
     receiptVerificationEnabled: zod_1.z.boolean().default(true),
     ktaBaseURL: zod_1.z.string().url().default("https://knowthat.ai"),
 });
+// Constants
 exports.MCP_I_CAPABILITIES = [
     "handshake",
     "signing",
     "verification",
 ];
 exports.CLAIM_TOKEN_TTL_HOURS = 24;
-exports.KTA_BASE_URL = "https://knowthat.ai";
+exports.KTA_BASE_URL = "https://knowthat.ai"; // Placeholder for docs/tests
+// Storage mode constants
 exports.DEFAULT_STORAGE_MODE = "ktaEncrypted";
 exports.STORAGE_MODE_ENV_VAR = "MCPI_STORAGE_MODE";
+// Receipt schema constants
 exports.RECEIPT_SCHEMA_ID = "https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json";
 exports.CONTENT_HASH_REGEX = /^sha256:[a-f0-9]{64}$/;

package/dist/runtime/errors.d.ts

@@ -0,0 +1,347 @@
+/**
+ * Runtime Error Contracts
+ *
+ * Error types and schemas for runtime errors, especially authorization errors
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+import { z } from 'zod';
+/**
+ * Display hint types for authorization UI
+ */
+export declare const DisplayHintSchema: z.ZodEnum<["link", "qr", "code"]>;
+export type DisplayHint = z.infer<typeof DisplayHintSchema>;
+/**
+ * Display options for authorization flow
+ */
+export declare const AuthorizationDisplaySchema: z.ZodObject<{
+    /** Optional title for the authorization screen */
+    title: z.ZodOptional<z.ZodString>;
+    /** Hints for how to display authorization (link, QR code, or code) */
+    hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+    /** Optional short authorization code */
+    authorizationCode: z.ZodOptional<z.ZodString>;
+    /** Optional QR code URL */
+    qrUrl: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** Optional title for the authorization screen */
+    title: z.ZodOptional<z.ZodString>;
+    /** Hints for how to display authorization (link, QR code, or code) */
+    hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+    /** Optional short authorization code */
+    authorizationCode: z.ZodOptional<z.ZodString>;
+    /** Optional QR code URL */
+    qrUrl: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** Optional title for the authorization screen */
+    title: z.ZodOptional<z.ZodString>;
+    /** Hints for how to display authorization (link, QR code, or code) */
+    hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+    /** Optional short authorization code */
+    authorizationCode: z.ZodOptional<z.ZodString>;
+    /** Optional QR code URL */
+    qrUrl: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type AuthorizationDisplay = z.infer<typeof AuthorizationDisplaySchema>;
+/**
+ * NeedsAuthorizationError Schema
+ *
+ * Error returned when a request requires authorization.
+ * Includes a resumeToken and authorizationUrl for the authorization flow.
+ */
+export declare const NeedsAuthorizationErrorSchema: z.ZodObject<{
+    /** Error code */
+    error: z.ZodLiteral<"needs_authorization">;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: z.ZodString;
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: z.ZodString;
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: z.ZodNumber;
+    /** Required scopes for authorization */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** Optional display configuration for authorization UI */
+    display: z.ZodOptional<z.ZodObject<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Optional additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** Error code */
+    error: z.ZodLiteral<"needs_authorization">;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: z.ZodString;
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: z.ZodString;
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: z.ZodNumber;
+    /** Required scopes for authorization */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** Optional display configuration for authorization UI */
+    display: z.ZodOptional<z.ZodObject<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Optional additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** Error code */
+    error: z.ZodLiteral<"needs_authorization">;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: z.ZodString;
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: z.ZodString;
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: z.ZodNumber;
+    /** Required scopes for authorization */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** Optional display configuration for authorization UI */
+    display: z.ZodOptional<z.ZodObject<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Optional additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type NeedsAuthorizationError = z.infer<typeof NeedsAuthorizationErrorSchema>;
+/**
+ * Generic Error Schema
+ *
+ * Standard error format for all runtime errors
+ */
+export declare const RuntimeErrorSchema: z.ZodObject<{
+    /** Error code */
+    error: z.ZodString;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** Optional error details */
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /** HTTP status code (if applicable) */
+    httpStatus: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    error: string;
+    details?: Record<string, any> | undefined;
+    httpStatus?: number | undefined;
+}, {
+    message: string;
+    error: string;
+    details?: Record<string, any> | undefined;
+    httpStatus?: number | undefined;
+}>;
+export type RuntimeError = z.infer<typeof RuntimeErrorSchema>;
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a needs authorization error
+ *
+ * @param error - The error to validate
+ * @returns Validation result
+ */
+export declare function validateNeedsAuthorizationError(error: unknown): z.SafeParseReturnType<z.objectInputType<{
+    /** Error code */
+    error: z.ZodLiteral<"needs_authorization">;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: z.ZodString;
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: z.ZodString;
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: z.ZodNumber;
+    /** Required scopes for authorization */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** Optional display configuration for authorization UI */
+    display: z.ZodOptional<z.ZodObject<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Optional additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">, z.objectOutputType<{
+    /** Error code */
+    error: z.ZodLiteral<"needs_authorization">;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: z.ZodString;
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: z.ZodString;
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: z.ZodNumber;
+    /** Required scopes for authorization */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** Optional display configuration for authorization UI */
+    display: z.ZodOptional<z.ZodObject<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        /** Optional title for the authorization screen */
+        title: z.ZodOptional<z.ZodString>;
+        /** Hints for how to display authorization (link, QR code, or code) */
+        hint: z.ZodOptional<z.ZodArray<z.ZodEnum<["link", "qr", "code"]>, "many">>;
+        /** Optional short authorization code */
+        authorizationCode: z.ZodOptional<z.ZodString>;
+        /** Optional QR code URL */
+        qrUrl: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Optional additional context */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Check if error is a needs authorization error
+ *
+ * @param error - The error to check
+ * @returns true if it's a needs authorization error
+ */
+export declare function isNeedsAuthorizationError(error: any): error is NeedsAuthorizationError;
+/**
+ * Create a needs authorization error
+ *
+ * @param config - Configuration for the error
+ * @returns NeedsAuthorizationError instance
+ */
+export declare function createNeedsAuthorizationError(config: {
+    message: string;
+    authorizationUrl: string;
+    resumeToken: string;
+    expiresAt: number;
+    scopes: string[];
+    display?: AuthorizationDisplay;
+}): NeedsAuthorizationError;
+/**
+ * Constants
+ */
+/**
+ * Error codes
+ */
+export declare const ERROR_CODES: Readonly<{
+    readonly NEEDS_AUTHORIZATION: "needs_authorization";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly INSUFFICIENT_SCOPE: "insufficient_scope";
+    readonly INVALID_SIGNATURE: "invalid_signature";
+    readonly DELEGATION_REVOKED: "delegation_revoked";
+    readonly CREDENTIAL_REVOKED: "credential_revoked";
+}>;
+export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];

package/dist/runtime/errors.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Runtime Error Contracts
+ *
+ * Error types and schemas for runtime errors, especially authorization errors
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CODES = exports.RuntimeErrorSchema = exports.NeedsAuthorizationErrorSchema = exports.AuthorizationDisplaySchema = exports.DisplayHintSchema = void 0;
+exports.validateNeedsAuthorizationError = validateNeedsAuthorizationError;
+exports.isNeedsAuthorizationError = isNeedsAuthorizationError;
+exports.createNeedsAuthorizationError = createNeedsAuthorizationError;
+const zod_1 = require("zod");
+/**
+ * Display hint types for authorization UI
+ */
+exports.DisplayHintSchema = zod_1.z.enum(['link', 'qr', 'code']);
+/**
+ * Display options for authorization flow
+ */
+exports.AuthorizationDisplaySchema = zod_1.z.object({
+    /** Optional title for the authorization screen */
+    title: zod_1.z.string().optional(),
+    /** Hints for how to display authorization (link, QR code, or code) */
+    hint: zod_1.z.array(exports.DisplayHintSchema).optional(),
+    /** Optional short authorization code */
+    authorizationCode: zod_1.z.string().optional(),
+    /** Optional QR code URL */
+    qrUrl: zod_1.z.string().url().optional(),
+}).passthrough();
+/**
+ * NeedsAuthorizationError Schema
+ *
+ * Error returned when a request requires authorization.
+ * Includes a resumeToken and authorizationUrl for the authorization flow.
+ */
+exports.NeedsAuthorizationErrorSchema = zod_1.z.object({
+    /** Error code */
+    error: zod_1.z.literal('needs_authorization'),
+    /** Human-readable error message */
+    message: zod_1.z.string().min(1),
+    /** URL for the user to authorize (includes resume token) */
+    authorizationUrl: zod_1.z.string().url(),
+    /** Short-lived resume token for continuing after authorization */
+    resumeToken: zod_1.z.string().min(1),
+    /** Expiration timestamp for the resume token (milliseconds since epoch) */
+    expiresAt: zod_1.z.number().int().positive(),
+    /** Required scopes for authorization */
+    scopes: zod_1.z.array(zod_1.z.string()),
+    /** Optional display configuration for authorization UI */
+    display: exports.AuthorizationDisplaySchema.optional(),
+    /** Optional additional context */
+    context: zod_1.z.record(zod_1.z.any()).optional(),
+}).passthrough();
+/**
+ * Generic Error Schema
+ *
+ * Standard error format for all runtime errors
+ */
+exports.RuntimeErrorSchema = zod_1.z.object({
+    /** Error code */
+    error: zod_1.z.string().min(1),
+    /** Human-readable error message */
+    message: zod_1.z.string().min(1),
+    /** Optional error details */
+    details: zod_1.z.record(zod_1.z.any()).optional(),
+    /** HTTP status code (if applicable) */
+    httpStatus: zod_1.z.number().int().min(400).max(599).optional(),
+});
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a needs authorization error
+ *
+ * @param error - The error to validate
+ * @returns Validation result
+ */
+function validateNeedsAuthorizationError(error) {
+    return exports.NeedsAuthorizationErrorSchema.safeParse(error);
+}
+/**
+ * Check if error is a needs authorization error
+ *
+ * @param error - The error to check
+ * @returns true if it's a needs authorization error
+ */
+function isNeedsAuthorizationError(error) {
+    return error && error.error === 'needs_authorization';
+}
+/**
+ * Create a needs authorization error
+ *
+ * @param config - Configuration for the error
+ * @returns NeedsAuthorizationError instance
+ */
+function createNeedsAuthorizationError(config) {
+    return {
+        error: 'needs_authorization',
+        ...config,
+    };
+}
+/**
+ * Constants
+ */
+/**
+ * Error codes
+ */
+exports.ERROR_CODES = Object.freeze({
+    NEEDS_AUTHORIZATION: 'needs_authorization',
+    INVALID_TOKEN: 'invalid_token',
+    TOKEN_EXPIRED: 'token_expired',
+    INSUFFICIENT_SCOPE: 'insufficient_scope',
+    INVALID_SIGNATURE: 'invalid_signature',
+    DELEGATION_REVOKED: 'delegation_revoked',
+    CREDENTIAL_REVOKED: 'credential_revoked',
+});