@kya-os/contracts 1.2.1 → 1.2.2

package/dist/runtime/errors.d.ts

@@ -0,0 +1,348 @@
+/**
+ * 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];
+//# sourceMappingURL=errors.d.ts.map

package/dist/runtime/errors.js

@@ -0,0 +1,120 @@
+"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',
+});
+//# sourceMappingURL=errors.js.map

package/dist/runtime/headers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Runtime Header Contracts
+ *
+ * Header contracts for downstream services
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+/**
+ * Downstream Headers Interface
+ *
+ * Headers passed to downstream services after verification
+ */
+export interface DownstreamHeaders {
+    /** DID of the verified agent */
+    'X-Agent-DID': string;
+    /** Optional delegation ID */
+    'X-Delegation-Id'?: string;
+    /** Optional delegation chain (format: vc_id>del_id>...) */
+    'X-Delegation-Chain'?: string;
+    /** Proof ID for audit trail */
+    'X-MCPI-Proof-Id': string;
+    /** Optional CRISP spend info (JSON string: {unit, delta, remaining}) */
+    'X-CRISP-Spend'?: string;
+    /** Optional session ID */
+    'X-Session-Id'?: string;
+    /** Optional scopes */
+    'X-Scopes'?: string;
+}
+/**
+ * Header names as constants for type safety
+ */
+export declare const DOWNSTREAM_HEADER_NAMES: Readonly<{
+    readonly AGENT_DID: "X-Agent-DID";
+    readonly DELEGATION_ID: "X-Delegation-Id";
+    readonly DELEGATION_CHAIN: "X-Delegation-Chain";
+    readonly PROOF_ID: "X-MCPI-Proof-Id";
+    readonly CRISP_SPEND: "X-CRISP-Spend";
+    readonly SESSION_ID: "X-Session-Id";
+    readonly SCOPES: "X-Scopes";
+}>;
+/**
+ * CRISP Spend Info
+ *
+ * Structure for X-CRISP-Spend header value
+ */
+export interface CrispSpendInfo {
+    /** Unit of spending */
+    unit: 'USD' | 'ops' | 'points';
+    /** Amount spent in this request */
+    delta?: number;
+    /** Remaining budget */
+    remaining?: number;
+}
+/**
+ * Helper to serialize CRISP spend info to header value
+ *
+ * @param info - CRISP spend info
+ * @returns JSON string for header
+ */
+export declare function serializeCrispSpend(info: CrispSpendInfo): string;
+/**
+ * Helper to parse CRISP spend info from header value
+ *
+ * @param headerValue - JSON string from header
+ * @returns Parsed CRISP spend info or null if invalid
+ */
+export declare function parseCrispSpend(headerValue: string): CrispSpendInfo | null;
+/**
+ * Helper to create downstream headers
+ *
+ * @param config - Configuration for headers
+ * @returns DownstreamHeaders object
+ */
+export declare function createDownstreamHeaders(config: {
+    agentDid: string;
+    proofId: string;
+    delegationId?: string;
+    delegationChain?: string;
+    crispSpend?: CrispSpendInfo;
+    sessionId?: string;
+    scopes?: string[];
+}): DownstreamHeaders;
+//# sourceMappingURL=headers.d.ts.map

package/dist/runtime/headers.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Runtime Header Contracts
+ *
+ * Header contracts for downstream services
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOWNSTREAM_HEADER_NAMES = void 0;
+exports.serializeCrispSpend = serializeCrispSpend;
+exports.parseCrispSpend = parseCrispSpend;
+exports.createDownstreamHeaders = createDownstreamHeaders;
+/**
+ * Header names as constants for type safety
+ */
+exports.DOWNSTREAM_HEADER_NAMES = Object.freeze({
+    AGENT_DID: 'X-Agent-DID',
+    DELEGATION_ID: 'X-Delegation-Id',
+    DELEGATION_CHAIN: 'X-Delegation-Chain',
+    PROOF_ID: 'X-MCPI-Proof-Id',
+    CRISP_SPEND: 'X-CRISP-Spend',
+    SESSION_ID: 'X-Session-Id',
+    SCOPES: 'X-Scopes',
+});
+/**
+ * Helper to serialize CRISP spend info to header value
+ *
+ * @param info - CRISP spend info
+ * @returns JSON string for header
+ */
+function serializeCrispSpend(info) {
+    return JSON.stringify(info);
+}
+/**
+ * Helper to parse CRISP spend info from header value
+ *
+ * @param headerValue - JSON string from header
+ * @returns Parsed CRISP spend info or null if invalid
+ */
+function parseCrispSpend(headerValue) {
+    try {
+        const parsed = JSON.parse(headerValue);
+        if (parsed && typeof parsed.unit === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Helper to create downstream headers
+ *
+ * @param config - Configuration for headers
+ * @returns DownstreamHeaders object
+ */
+function createDownstreamHeaders(config) {
+    const headers = {
+        'X-Agent-DID': config.agentDid,
+        'X-MCPI-Proof-Id': config.proofId,
+    };
+    if (config.delegationId) {
+        headers['X-Delegation-Id'] = config.delegationId;
+    }
+    if (config.delegationChain) {
+        headers['X-Delegation-Chain'] = config.delegationChain;
+    }
+    if (config.crispSpend) {
+        headers['X-CRISP-Spend'] = serializeCrispSpend(config.crispSpend);
+    }
+    if (config.sessionId) {
+        headers['X-Session-Id'] = config.sessionId;
+    }
+    if (config.scopes && config.scopes.length > 0) {
+        headers['X-Scopes'] = config.scopes.join(',');
+    }
+    return headers;
+}
+//# sourceMappingURL=headers.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runtime Module Exports
+ */
+export * from './errors.js';
+export * from './headers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Runtime Module Exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./headers.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/tlkrc/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TLKRC Module Exports
+ */
+export * from './rotation.js';
+//# sourceMappingURL=index.d.ts.map