@kya-os/contracts 1.0.0-alpha

package/README.md

@@ -0,0 +1,130 @@
+# @kya-os/contracts
+
+Shared types and schemas for the XMCP-I ecosystem. This package provides a single source of truth for all contracts used across runtime, CLI, verifier, and registry components.
+
+## Features
+
+- **Type-safe contracts** using Zod schemas
+- **Subpath exports** for modular imports
+- **JSON schemas** with versioning for external validation
+- **Zero runtime dependencies** (except Zod)
+- **ESM-only** with tree-shaking support
+
+## Installation
+
+```bash
+npm install @kya-os/contracts
+```
+
+## Usage
+
+### Subpath Imports
+
+```typescript
+// Import specific namespaces
+import { HandshakeRequest, SessionContext } from "@kya-os/contracts/handshake";
+import { DetachedProof, ProofMeta } from "@kya-os/contracts/proof";
+import { AgentContext, AGENT_HEADERS } from "@kya-os/contracts/verifier";
+import {
+  RegistrationResult,
+  MCP_I_CAPABILITIES,
+} from "@kya-os/contracts/registry";
+import { StatusReport, ERROR_CODES } from "@kya-os/contracts/cli";
+
+// Or import everything
+import * as Contracts from "@kya-os/contracts";
+```
+
+### Schema Validation
+
+```typescript
+import { DetachedProofSchema } from "@kya-os/contracts/proof";
+
+// Validate data at runtime
+const result = DetachedProofSchema.safeParse(data);
+if (result.success) {
+  // data is now typed as DetachedProof
+  console.log(result.data.meta.did);
+}
+```
+
+### JSON Schemas
+
+JSON schemas are available under the `/schemas/**` subpath:
+
+```typescript
+// Access versioned JSON schemas
+import proofSchema from "@kya-os/contracts/schemas/proof/v1.0.0.json";
+import agentSchema from "@kya-os/contracts/schemas/well-known/agent/v1.0.0.json";
+```
+
+## Namespaces
+
+### Handshake (`/handshake`)
+
+- `HandshakeRequest` - Nonce, audience, timestamp validation
+- `SessionContext` - Session management and TTL
+- `NonceCacheEntry` - Nonce cache storage
+
+### Proof (`/proof`)
+
+- `DetachedProof` - JWS signature with metadata
+- `ProofMeta` - Proof metadata fields
+- `AuditRecord` - Audit logging format
+
+### Verifier (`/verifier`)
+
+- `AgentContext` - Verified agent information
+- `VerifierResult` - Middleware validation results
+- `AGENT_HEADERS` - Frozen header name constants
+
+### Registry (`/registry`)
+
+- `RegistrationResult` - KTA registration response
+- `AgentStatus` - Agent status reporting
+- `MCP_I_CAPABILITIES` - Protocol capability constants
+
+### CLI (`/cli`)
+
+- `StatusReport` - CLI status command output
+- `ScaffolderResult` - Scaffolder operation results
+- `ERROR_CODES` - Error code constants
+
+## Versioning
+
+This package follows semantic versioning:
+
+- **Major**: Breaking changes to existing contracts
+- **Minor**: Additive changes (new fields, optional properties)
+- **Patch**: Bug fixes and documentation updates
+
+JSON schemas are versioned independently under `/schemas/{namespace}/v{major}.{minor}.{patch}.json`.
+
+## Type Safety
+
+All types are derived from Zod schemas to ensure runtime validation matches TypeScript types:
+
+```typescript
+// Schema definition
+export const ProofMetaSchema = z.object({
+  did: z.string().min(1),
+  kid: z.string().min(1),
+  // ...
+});
+
+// Type derived from schema
+export type ProofMeta = z.infer<typeof ProofMetaSchema>;
+```
+
+## Bundle Size
+
+This package is optimized for minimal bundle impact:
+
+- **Tarball size**: < 50 KB
+- **Side effects**: None (`"sideEffects": false`)
+- **Tree-shaking**: Full ESM support
+- **Dependencies**: Only Zod for schema validation
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,242 @@
+import { z } from "zod";
+/**
+ * CLI command schemas and results
+ */
+export declare const IdentityConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    did: z.ZodString;
+    keyId: z.ZodString;
+    privateKey: z.ZodString;
+    publicKey: z.ZodString;
+    createdAt: z.ZodString;
+    lastRotated: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    did: string;
+    keyId: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    lastRotated: string;
+}, {
+    version: "1.0";
+    did: string;
+    keyId: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    lastRotated: string;
+}>;
+export declare const KeyRotationResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    oldKeyId: z.ZodString;
+    newKeyId: z.ZodString;
+    did: z.ZodString;
+    mode: z.ZodEnum<["dev", "prod"]>;
+    delegated: z.ZodBoolean;
+    forced: z.ZodBoolean;
+    auditLine: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    success: boolean;
+    oldKeyId: string;
+    newKeyId: string;
+    mode: "dev" | "prod";
+    delegated: boolean;
+    forced: boolean;
+    auditLine: string;
+}, {
+    did: string;
+    success: boolean;
+    oldKeyId: string;
+    newKeyId: string;
+    mode: "dev" | "prod";
+    delegated: boolean;
+    forced: boolean;
+    auditLine: string;
+}>;
+export declare const StatusReportSchema: z.ZodObject<{
+    did: z.ZodString;
+    keyId: z.ZodString;
+    ktaURL: z.ZodString;
+    mirrorStatus: z.ZodEnum<["pending", "success", "error"]>;
+    lastHandshake: z.ZodOptional<z.ZodNumber>;
+    environment: z.ZodEnum<["dev", "prod"]>;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    keyId: string;
+    ktaURL: string;
+    mirrorStatus: "success" | "pending" | "error";
+    environment: "dev" | "prod";
+    lastHandshake?: number | undefined;
+}, {
+    did: string;
+    keyId: string;
+    ktaURL: string;
+    mirrorStatus: "success" | "pending" | "error";
+    environment: "dev" | "prod";
+    lastHandshake?: number | undefined;
+}>;
+export declare const DoctorResultSchema: z.ZodObject<{
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        compatible: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        name: string;
+        compatible: boolean;
+    }, {
+        version: string;
+        name: string;
+        compatible: boolean;
+    }>, "many">;
+    xmcpUpstream: z.ZodObject<{
+        version: z.ZodString;
+        compatible: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        compatible: boolean;
+    }, {
+        version: string;
+        compatible: boolean;
+    }>;
+    environment: z.ZodObject<{
+        valid: z.ZodBoolean;
+        missing: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        valid: boolean;
+        missing: string[];
+    }, {
+        valid: boolean;
+        missing: string[];
+    }>;
+    kta: z.ZodObject<{
+        reachable: z.ZodBoolean;
+        authenticated: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        reachable: boolean;
+        authenticated: boolean;
+    }, {
+        reachable: boolean;
+        authenticated: boolean;
+    }>;
+    cache: z.ZodObject<{
+        type: z.ZodString;
+        functional: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        functional: boolean;
+    }, {
+        type: string;
+        functional: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    environment: {
+        valid: boolean;
+        missing: string[];
+    };
+    packages: {
+        version: string;
+        name: string;
+        compatible: boolean;
+    }[];
+    xmcpUpstream: {
+        version: string;
+        compatible: boolean;
+    };
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+    };
+    cache: {
+        type: string;
+        functional: boolean;
+    };
+}, {
+    environment: {
+        valid: boolean;
+        missing: string[];
+    };
+    packages: {
+        version: string;
+        name: string;
+        compatible: boolean;
+    }[];
+    xmcpUpstream: {
+        version: string;
+        compatible: boolean;
+    };
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+    };
+    cache: {
+        type: string;
+        functional: boolean;
+    };
+}>;
+export declare const ScaffolderOptionsSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    xmcpVersion: z.ZodOptional<z.ZodString>;
+    xmcpChannel: z.ZodOptional<z.ZodEnum<["latest", "next"]>>;
+    noIdentity: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    noIdentity: boolean;
+    xmcpVersion?: string | undefined;
+    xmcpChannel?: "latest" | "next" | undefined;
+}, {
+    projectName: string;
+    xmcpVersion?: string | undefined;
+    xmcpChannel?: "latest" | "next" | undefined;
+    noIdentity?: boolean | undefined;
+}>;
+export declare const ScaffolderResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    projectPath: z.ZodString;
+    xmcpVersion: z.ZodString;
+    identityEnabled: z.ZodBoolean;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    xmcpVersion: string;
+    projectPath: string;
+    identityEnabled: boolean;
+    warnings?: string[] | undefined;
+}, {
+    success: boolean;
+    xmcpVersion: string;
+    projectPath: string;
+    identityEnabled: boolean;
+    warnings?: string[] | undefined;
+}>;
+export type IdentityConfig = z.infer<typeof IdentityConfigSchema>;
+export type KeyRotationResult = z.infer<typeof KeyRotationResultSchema>;
+export type StatusReport = z.infer<typeof StatusReportSchema>;
+export type DoctorResult = z.infer<typeof DoctorResultSchema>;
+export type ScaffolderOptions = z.infer<typeof ScaffolderOptionsSchema>;
+export type ScaffolderResult = z.infer<typeof ScaffolderResultSchema>;
+export declare const ERROR_CODES: {
+    readonly XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF";
+    readonly XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY";
+    readonly XMCP_I_EMIRRORPENDING: "XMCP_I_EMIRRORPENDING";
+    readonly XMCP_I_EHANDSHAKE: "XMCP_I_EHANDSHAKE";
+    readonly XMCP_I_ESESSION: "XMCP_I_ESESSION";
+    readonly XMCP_I_ECLAIM: "XMCP_I_ECLAIM";
+    readonly XMCP_I_ECONFIG: "XMCP_I_ECONFIG";
+    readonly XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME";
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+export declare const CLI_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly BADPROOF: 20;
+    readonly NOIDENTITY: 21;
+    readonly HANDSHAKE: 22;
+    readonly SESSION: 23;
+    readonly CLAIM: 24;
+    readonly CONFIG: 25;
+    readonly RUNTIME: 26;
+};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;EAQ/B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;EASlC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAO7B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwB7B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAKlC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;EAMjC,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAGtE,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAGjD,eAAO,MAAM,cAAc;;;;;;;;;;CAUjB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+/**
+ * CLI command schemas and results
+ */
+export const IdentityConfigSchema = z.object({
+    version: z.literal("1.0"),
+    did: z.string().min(1),
+    keyId: z.string().min(1),
+    privateKey: z.string().min(1), // base64-encoded Ed25519 private key
+    publicKey: z.string().min(1), // base64-encoded Ed25519 public key
+    createdAt: z.string().datetime(),
+    lastRotated: z.string().datetime(),
+});
+export const KeyRotationResultSchema = z.object({
+    success: z.boolean(),
+    oldKeyId: z.string().min(1),
+    newKeyId: z.string().min(1),
+    did: z.string().min(1),
+    mode: z.enum(["dev", "prod"]),
+    delegated: z.boolean(),
+    forced: z.boolean(),
+    auditLine: z.string().min(1),
+});
+export const StatusReportSchema = z.object({
+    did: z.string().min(1),
+    keyId: z.string().min(1),
+    ktaURL: z.string().url(),
+    mirrorStatus: z.enum(["pending", "success", "error"]),
+    lastHandshake: z.number().int().positive().optional(),
+    environment: z.enum(["dev", "prod"]),
+});
+export const DoctorResultSchema = z.object({
+    packages: z.array(z.object({
+        name: z.string(),
+        version: z.string(),
+        compatible: z.boolean(),
+    })),
+    xmcpUpstream: z.object({
+        version: z.string(),
+        compatible: z.boolean(),
+    }),
+    environment: z.object({
+        valid: z.boolean(),
+        missing: z.array(z.string()),
+    }),
+    kta: z.object({
+        reachable: z.boolean(),
+        authenticated: z.boolean(),
+    }),
+    cache: z.object({
+        type: z.string(),
+        functional: z.boolean(),
+    }),
+});
+export const ScaffolderOptionsSchema = z.object({
+    projectName: z.string().min(1),
+    xmcpVersion: z.string().optional(),
+    xmcpChannel: z.enum(["latest", "next"]).optional(),
+    noIdentity: z.boolean().default(false),
+});
+export const ScaffolderResultSchema = z.object({
+    success: z.boolean(),
+    projectPath: z.string().min(1),
+    xmcpVersion: z.string().min(1),
+    identityEnabled: z.boolean(),
+    warnings: z.array(z.string()).optional(),
+});
+// Error codes as string literal union
+export const ERROR_CODES = {
+    XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF",
+    XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY",
+    XMCP_I_EMIRRORPENDING: "XMCP_I_EMIRRORPENDING",
+    XMCP_I_EHANDSHAKE: "XMCP_I_EHANDSHAKE",
+    XMCP_I_ESESSION: "XMCP_I_ESESSION",
+    XMCP_I_ECLAIM: "XMCP_I_ECLAIM",
+    XMCP_I_ECONFIG: "XMCP_I_ECONFIG",
+    XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME",
+};
+// CLI exit codes
+export const CLI_EXIT_CODES = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    BADPROOF: 20,
+    NOIDENTITY: 21,
+    HANDSHAKE: 22,
+    SESSION: 23,
+    CLAIM: 24,
+    CONFIG: 25,
+    RUNTIME: 26,
+};
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/handshake.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+/**
+ * Handshake and session management schemas
+ */
+export declare const HandshakeRequestSchema: z.ZodObject<{
+    nonce: z.ZodString;
+    audience: z.ZodString;
+    timestamp: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    audience: string;
+    timestamp: number;
+}, {
+    nonce: string;
+    audience: string;
+    timestamp: number;
+}>;
+export declare const SessionContextSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    audience: z.ZodString;
+    nonce: z.ZodString;
+    timestamp: z.ZodNumber;
+    createdAt: z.ZodNumber;
+    lastActivity: z.ZodNumber;
+    ttlMinutes: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    createdAt: number;
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    sessionId: string;
+    lastActivity: number;
+    ttlMinutes: number;
+}, {
+    createdAt: number;
+    nonce: string;
+    audience: string;
+    timestamp: number;
+    sessionId: string;
+    lastActivity: number;
+    ttlMinutes?: number | undefined;
+}>;
+export declare const NonceCacheEntrySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    expiresAt: number;
+}, {
+    sessionId: string;
+    expiresAt: number;
+}>;
+export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
+export type SessionContext = z.infer<typeof SessionContextSchema>;
+export type NonceCacheEntry = z.infer<typeof NonceCacheEntrySchema>;
+/**
+ * Nonce cache interface for replay prevention
+ */
+export interface NonceCache {
+    /**
+     * Check if a nonce exists in the cache
+     */
+    has(nonce: string): Promise<boolean>;
+    /**
+     * Add a nonce to the cache with TTL
+     * MUST ensure atomic add-if-absent semantics for replay prevention
+     */
+    add(nonce: string, ttl: number): Promise<void>;
+    /**
+     * Clean up expired entries
+     * Should be safe to call frequently and should be no-op for backends that auto-expire
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Configuration for nonce cache implementations
+ */
+export declare const NonceCacheConfigSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<["memory", "redis", "dynamodb", "cloudflare-kv"]>>;
+    redis: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        keyPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        keyPrefix: string;
+    }, {
+        url: string;
+        keyPrefix?: string | undefined;
+    }>>;
+    dynamodb: z.ZodOptional<z.ZodObject<{
+        tableName: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        keyAttribute: z.ZodDefault<z.ZodString>;
+        ttlAttribute: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tableName: string;
+        keyAttribute: string;
+        ttlAttribute: string;
+        region?: string | undefined;
+    }, {
+        tableName: string;
+        region?: string | undefined;
+        keyAttribute?: string | undefined;
+        ttlAttribute?: string | undefined;
+    }>>;
+    cloudflareKv: z.ZodOptional<z.ZodObject<{
+        namespace: z.ZodString;
+        keyPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        keyPrefix: string;
+        namespace: string;
+    }, {
+        namespace: string;
+        keyPrefix?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    redis?: {
+        url: string;
+        keyPrefix: string;
+    } | undefined;
+    dynamodb?: {
+        tableName: string;
+        keyAttribute: string;
+        ttlAttribute: string;
+        region?: string | undefined;
+    } | undefined;
+    cloudflareKv?: {
+        keyPrefix: string;
+        namespace: string;
+    } | undefined;
+}, {
+    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    redis?: {
+        url: string;
+        keyPrefix?: string | undefined;
+    } | undefined;
+    dynamodb?: {
+        tableName: string;
+        region?: string | undefined;
+        keyAttribute?: string | undefined;
+        ttlAttribute?: string | undefined;
+    } | undefined;
+    cloudflareKv?: {
+        namespace: string;
+        keyPrefix?: string | undefined;
+    } | undefined;
+}>;
+export type NonceCacheConfig = z.infer<typeof NonceCacheConfigSchema>;
+export declare const DEFAULT_SESSION_TTL_MINUTES = 30;
+export declare const DEFAULT_TIMESTAMP_SKEW_SECONDS = 120;
+export declare const NONCE_LENGTH_BYTES = 16;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAIjC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;EAQ/B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;EAGhC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErC;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsBjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAGtE,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAClD,eAAO,MAAM,kBAAkB,KAAK,CAAC"}

package/dist/handshake.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/**
+ * Handshake and session management schemas
+ */
+export const HandshakeRequestSchema = z.object({
+    nonce: z.string().min(1),
+    audience: z.string().min(1),
+    timestamp: z.number().int().positive(),
+});
+export const SessionContextSchema = z.object({
+    sessionId: z.string().min(1),
+    audience: z.string().min(1),
+    nonce: z.string().min(1),
+    timestamp: z.number().int().positive(),
+    createdAt: z.number().int().positive(),
+    lastActivity: z.number().int().positive(),
+    ttlMinutes: z.number().int().positive().default(30),
+});
+export const NonceCacheEntrySchema = z.object({
+    sessionId: z.string().min(1),
+    expiresAt: z.number().int().positive(),
+});
+/**
+ * Configuration for nonce cache implementations
+ */
+export const NonceCacheConfigSchema = z.object({
+    type: z.enum(["memory", "redis", "dynamodb", "cloudflare-kv"]).optional(),
+    redis: z
+        .object({
+        url: z.string().url(),
+        keyPrefix: z.string().default("xmcpi:nonce:"),
+    })
+        .optional(),
+    dynamodb: z
+        .object({
+        tableName: z.string(),
+        region: z.string().optional(),
+        keyAttribute: z.string().default("nonce"),
+        ttlAttribute: z.string().default("expiresAt"),
+    })
+        .optional(),
+    cloudflareKv: z
+        .object({
+        namespace: z.string(),
+        keyPrefix: z.string().default("nonce:"),
+    })
+        .optional(),
+});
+// Constants
+export const DEFAULT_SESSION_TTL_MINUTES = 30;
+export const DEFAULT_TIMESTAMP_SKEW_SECONDS = 120;
+export const NONCE_LENGTH_BYTES = 16; // 128-bit
+//# sourceMappingURL=handshake.js.map

package/dist/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CACpD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AA6BH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzE,KAAK,EAAE,CAAC;SACL,MAAM,CAAC;QACN,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC;KAC9C,CAAC;SACD,QAAQ,EAAE;IACb,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC;QACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;QACzC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;KAC9C,CAAC;SACD,QAAQ,EAAE;IACb,YAAY,EAAE,CAAC;SACZ,MAAM,CAAC;QACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;KACxC,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAIH,YAAY;AACZ,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC,CAAC,UAAU"}