@kya-os/contracts 1.5.3-canary.2 → 1.5.3-canary.21

package/src/consent/schemas.ts

@@ -0,0 +1,334 @@
+/**
+ * Consent Schemas
+ *
+ * Zod schemas for runtime validation of consent-related data structures.
+ * All types are derived from these schemas using z.infer.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+
+import { z } from "zod";
+
+/**
+ * Consent Branding Schema
+ */
+export const consentBrandingSchema = z.object({
+  primaryColor: z
+    .string()
+    .regex(/^#[0-9A-Fa-f]{6}$/, "Must be a valid hex color (e.g., #0066CC)")
+    .optional(),
+  logoUrl: z.string().url("Must be a valid URL").optional(),
+  companyName: z
+    .string()
+    .max(100, "Company name must be 100 characters or less")
+    .optional(),
+  theme: z.enum(["light", "dark", "auto"]).optional(),
+});
+
+export type ConsentBranding = z.infer<typeof consentBrandingSchema>;
+
+/**
+ * Consent Terms Schema
+ */
+export const consentTermsSchema = z.object({
+  text: z
+    .string()
+    .max(10000, "Terms text must be 10000 characters or less")
+    .optional(),
+  url: z.string().url("Must be a valid URL").optional(),
+  version: z
+    .string()
+    .max(50, "Version must be 50 characters or less")
+    .optional(),
+  required: z.boolean().default(true),
+});
+
+export type ConsentTerms = z.infer<typeof consentTermsSchema>;
+
+/**
+ * Consent Custom Field Option Schema
+ */
+export const consentCustomFieldOptionSchema = z.object({
+  value: z.string().max(100, "Option value must be 100 characters or less"),
+  label: z.string().max(100, "Option label must be 100 characters or less"),
+});
+
+/**
+ * Consent Custom Field Schema
+ */
+export const consentCustomFieldSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1, "Field name is required")
+      .max(50, "Field name must be 50 characters or less")
+      .regex(
+        /^[a-zA-Z0-9_]+$/,
+        "Field name must contain only letters, numbers, and underscores"
+      ),
+    label: z
+      .string()
+      .min(1, "Field label is required")
+      .max(100, "Field label must be 100 characters or less"),
+    type: z.enum(["text", "textarea", "checkbox", "select"]),
+    required: z.boolean(),
+    placeholder: z
+      .string()
+      .max(200, "Placeholder must be 200 characters or less")
+      .optional(),
+    options: z
+      .array(consentCustomFieldOptionSchema)
+      .min(1, "Select fields must have at least one option")
+      .optional(),
+    pattern: z
+      .string()
+      .max(500, "Pattern must be 500 characters or less")
+      .optional(),
+  })
+  .refine(
+    (data) => {
+      // Select fields must have options
+      if (
+        data.type === "select" &&
+        (!data.options || data.options.length === 0)
+      ) {
+        return false;
+      }
+      // Non-select fields should not have options
+      if (data.type !== "select" && data.options) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message:
+        "Select fields must have options, and non-select fields must not have options",
+    }
+  );
+
+export type ConsentCustomField = z.infer<typeof consentCustomFieldSchema>;
+
+/**
+ * OAuth Identity Schema
+ *
+ * Represents a user's OAuth provider account information.
+ * Used in Phase 4 to link OAuth accounts to persistent User DIDs.
+ */
+export const oauthIdentitySchema = z.object({
+  /**
+   * OAuth provider name (e.g., "google", "github", "microsoft")
+   */
+  provider: z
+    .string()
+    .min(1, "Provider is required")
+    .max(50, "Provider name must be 50 characters or less"),
+
+  /**
+   * OAuth subject identifier (unique user ID from provider)
+   * @example "123456789" (Google), "github-user-id" (GitHub)
+   */
+  subject: z
+    .string()
+    .min(1, "Subject is required")
+    .max(255, "Subject must be 255 characters or less"),
+
+  /**
+   * User's email address from OAuth provider (optional)
+   */
+  email: z
+    .string()
+    .email("Must be a valid email address")
+    .max(255, "Email must be 255 characters or less")
+    .optional(),
+
+  /**
+   * User's display name from OAuth provider (optional)
+   */
+  name: z.string().max(255, "Name must be 255 characters or less").optional(),
+});
+
+export type OAuthIdentity = z.infer<typeof oauthIdentitySchema>;
+
+/**
+ * Consent Page Config Schema
+ */
+export const consentPageConfigSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  toolDescription: z
+    .string()
+    .max(500, "Tool description must be 500 characters or less"),
+  scopes: z.array(z.string()).min(0, "Scopes array cannot be negative"),
+  agentDid: z.string().min(1, "Agent DID is required"),
+  sessionId: z.string().min(1, "Session ID is required"),
+  projectId: z.string().min(1, "Project ID is required"),
+  provider: z.string().optional(), // Phase 2: OAuth provider name (e.g., "github", "google")
+  branding: consentBrandingSchema.optional(),
+  terms: consentTermsSchema.optional(),
+  customFields: z
+    .array(consentCustomFieldSchema)
+    .max(10, "Maximum 10 custom fields allowed")
+    .optional(),
+  serverUrl: z.string().url("Server URL must be a valid URL"),
+  autoClose: z.boolean().optional(),
+  /**
+   * Whether OAuth authorization is required immediately
+   * If true, the consent page will act as a landing page before redirecting
+   */
+  oauthRequired: z.boolean().optional(),
+  /**
+   * The OAuth authorization URL to redirect to
+   * Required if oauthRequired is true
+   */
+  oauthUrl: z.string().url().optional(),
+});
+
+export type ConsentPageConfig = z.infer<typeof consentPageConfigSchema>;
+
+/**
+ * Consent Approval Request Schema
+ *
+ * Note: Uses snake_case for API compatibility (agent_did, session_id, project_id)
+ *
+ * Phase 4 additions:
+ * - oauth_identity: Optional OAuth provider information for identity linking
+ * - user_did: Optional User DID for persistent identity (if already known)
+ */
+export const consentApprovalRequestSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  scopes: z.array(z.string()).min(0, "Scopes array cannot be negative"),
+  agent_did: z.string().min(1, "Agent DID is required"),
+  session_id: z.string().min(1, "Session ID is required"),
+  project_id: z.string().min(1, "Project ID is required"),
+  termsAccepted: z.boolean(),
+  termsVersion: z
+    .string()
+    .max(50, "Terms version must be 50 characters or less")
+    .optional(),
+  customFields: z.record(z.union([z.string(), z.boolean()])).optional(),
+
+  // Phase 4: OAuth identity linking
+  /**
+   * OAuth provider identity information (optional)
+   * Used to link OAuth accounts to persistent User DIDs
+   *
+   * CRITICAL: Uses .nullish() to accept null, undefined, or OAuthIdentity
+   * This matches JSON parsing behavior where missing fields become null
+   */
+  oauth_identity: oauthIdentitySchema.nullish(),
+
+  /**
+   * User DID (optional)
+   * If provided, represents the persistent User DID for this user
+   * Format: did:key:... or did:web:...
+   */
+  user_did: z
+    .string()
+    .regex(/^did:/, "Must be a valid DID format (starting with did:)")
+    .max(500, "DID must be 500 characters or less")
+    .optional(),
+});
+
+export type ConsentApprovalRequest = z.infer<
+  typeof consentApprovalRequestSchema
+>;
+
+/**
+ * Consent Approval Response Schema
+ */
+export const consentApprovalResponseSchema = z
+  .object({
+    success: z.boolean(),
+    delegation_id: z.string().min(1).optional(),
+    delegation_token: z.string().min(1).optional(),
+    error: z.string().optional(),
+    error_code: z.string().optional(),
+  })
+  .refine(
+    (data) => {
+      // If success is true, must have delegation_id and delegation_token
+      if (data.success) {
+        return !!data.delegation_id && !!data.delegation_token;
+      }
+      // If success is false, must have error or error_code
+      return !!data.error || !!data.error_code;
+    },
+    {
+      message:
+        "Successful responses must include delegation_id and delegation_token. Failed responses must include error or error_code",
+    }
+  );
+
+export type ConsentApprovalResponse = z.infer<
+  typeof consentApprovalResponseSchema
+>;
+
+/**
+ * Consent Config Schema
+ */
+export const consentConfigSchema = z.object({
+  branding: consentBrandingSchema.optional(),
+  terms: consentTermsSchema.optional(),
+  customFields: z
+    .array(consentCustomFieldSchema)
+    .max(10, "Maximum 10 custom fields allowed")
+    .optional(),
+  ui: z
+    .object({
+      theme: z.enum(["light", "dark", "auto"]).optional(),
+      popupEnabled: z.boolean().optional(),
+      autoClose: z.boolean().optional(),
+      autoCloseDelay: z
+        .number()
+        .int()
+        .positive()
+        .max(60000, "Auto-close delay must be 60000ms or less")
+        .optional(),
+    })
+    .optional(),
+});
+
+export type ConsentConfig = z.infer<typeof consentConfigSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a consent page config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+export function validateConsentPageConfig(config: unknown) {
+  return consentPageConfigSchema.safeParse(config);
+}
+
+/**
+ * Validate a consent approval request
+ *
+ * @param request - The request to validate
+ * @returns Validation result
+ */
+export function validateConsentApprovalRequest(request: unknown) {
+  return consentApprovalRequestSchema.safeParse(request);
+}
+
+/**
+ * Validate a consent approval response
+ *
+ * @param response - The response to validate
+ * @returns Validation result
+ */
+export function validateConsentApprovalResponse(response: unknown) {
+  return consentApprovalResponseSchema.safeParse(response);
+}
+
+/**
+ * Validate a consent config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+export function validateConsentConfig(config: unknown) {
+  return consentConfigSchema.safeParse(config);
+}

package/src/consent/types.ts

@@ -0,0 +1,199 @@
+/**
+ * Consent Types
+ *
+ * TypeScript type definitions for consent page configuration and approval handling.
+ * These types are used for server-hosted consent pages in HTTP/SSE transports.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+
+/**
+ * Consent Branding Configuration
+ *
+ * Customization options for consent page appearance
+ */
+export interface ConsentBranding {
+  /** Primary brand color (hex format, e.g., '#0066CC') */
+  primaryColor?: string;
+
+  /** Logo URL for display on consent page */
+  logoUrl?: string;
+
+  /** Company/application name */
+  companyName?: string;
+
+  /** Theme preference ('light', 'dark', or 'auto' for system preference) */
+  theme?: 'light' | 'dark' | 'auto';
+}
+
+/**
+ * Consent Terms Configuration
+ *
+ * Terms of service or privacy policy information
+ */
+export interface ConsentTerms {
+  /** Full terms text (displayed on page) */
+  text?: string;
+
+  /** URL to terms document */
+  url?: string;
+
+  /** Version identifier for terms */
+  version?: string;
+
+  /** Whether terms acceptance is required */
+  required?: boolean;
+}
+
+/**
+ * Consent Custom Field
+ *
+ * Additional fields to collect during consent (e.g., email, preferences)
+ */
+export interface ConsentCustomField {
+  /** Field name (used as form field name, must be valid identifier) */
+  name: string;
+
+  /** Display label for the field */
+  label: string;
+
+  /** Field type */
+  type: 'text' | 'textarea' | 'checkbox' | 'select';
+
+  /** Whether field is required */
+  required: boolean;
+
+  /** Placeholder text */
+  placeholder?: string;
+
+  /** Options for select fields */
+  options?: Array<{ value: string; label: string }>;
+
+  /** Validation pattern (regex) */
+  pattern?: string;
+}
+
+/**
+ * Consent Page Configuration
+ *
+ * Complete configuration for rendering a consent page
+ */
+export interface ConsentPageConfig {
+  /** Tool name requiring authorization */
+  tool: string;
+
+  /** Description of what the tool does */
+  toolDescription: string;
+
+  /** Scopes being requested */
+  scopes: string[];
+
+  /** Agent DID requesting authorization */
+  agentDid: string;
+
+  /** Session ID for tracking */
+  sessionId: string;
+
+  /** Project ID from AgentShield */
+  projectId: string;
+
+  /** Branding configuration */
+  branding?: ConsentBranding;
+
+  /** Terms configuration */
+  terms?: ConsentTerms;
+
+  /** Custom fields to collect */
+  customFields?: ConsentCustomField[];
+
+  /** Server URL for form submission */
+  serverUrl: string;
+
+  /** Whether to auto-close window after success */
+  autoClose?: boolean;
+}
+
+/**
+ * Consent Approval Request
+ *
+ * Request payload when user approves consent
+ */
+export interface ConsentApprovalRequest {
+  /** Tool name */
+  tool: string;
+
+  /** Approved scopes */
+  scopes: string[];
+
+  /** Agent DID (snake_case for API compatibility) */
+  agent_did: string;
+
+  /** Session ID (snake_case for API compatibility) */
+  session_id: string;
+
+  /** Project ID (snake_case for API compatibility) */
+  project_id: string;
+
+  /** Whether terms were accepted */
+  termsAccepted: boolean;
+
+  /** Terms version (if applicable) */
+  termsVersion?: string;
+
+  /** Custom field values */
+  customFields?: Record<string, string | boolean>;
+}
+
+/**
+ * Consent Approval Response
+ *
+ * Response after processing consent approval
+ */
+export interface ConsentApprovalResponse {
+  /** Whether approval was successful */
+  success: boolean;
+
+  /** Delegation ID (if successful) */
+  delegation_id?: string;
+
+  /** Delegation token (if successful) */
+  delegation_token?: string;
+
+  /** Error message (if failed) */
+  error?: string;
+
+  /** Error code (if failed) */
+  error_code?: string;
+}
+
+/**
+ * Consent Configuration
+ *
+ * Complete consent configuration fetched from AgentShield or defaults
+ */
+export interface ConsentConfig {
+  /** Branding configuration */
+  branding?: ConsentBranding;
+
+  /** Terms configuration */
+  terms?: ConsentTerms;
+
+  /** Custom fields configuration */
+  customFields?: ConsentCustomField[];
+
+  /** UI preferences */
+  ui?: {
+    /** Theme preference */
+    theme?: 'light' | 'dark' | 'auto';
+
+    /** Whether popup mode is enabled */
+    popupEnabled?: boolean;
+
+    /** Whether to auto-close after success */
+    autoClose?: boolean;
+
+    /** Delay before auto-close (milliseconds) */
+    autoCloseDelay?: number;
+  };
+}
+

package/src/dashboard-config/default-config.json

@@ -0,0 +1,86 @@
+{
+  "identity": {
+    "agentDid": "",
+    "environment": "development",
+    "storageLocation": "env-vars"
+  },
+  "proofing": {
+    "enabled": true,
+    "destinations": [
+      {
+        "type": "agentshield",
+        "apiUrl": "https://kya.vouched.id"
+      }
+    ],
+    "batchQueue": {
+      "maxBatchSize": 10,
+      "flushIntervalMs": 5000,
+      "maxRetries": 3
+    }
+  },
+  "delegation": {
+    "enabled": true,
+    "enforceStrictly": false,
+    "verifier": {
+      "type": "agentshield",
+      "apiUrl": "https://kya.vouched.id/api/v1/bouncer/delegations/verify",
+      "cacheTtl": 300000
+    },
+    "authorization": {
+      "authorizationUrl": "https://kya.vouched.id/api/v1/bouncer/delegations/authorize",
+      "minReputationScore": 80,
+      "resumeTokenTtl": 3600000,
+      "requireAuthForUnknown": false
+    }
+  },
+  "toolProtection": {
+    "source": "agentshield",
+    "agentShield": {
+      "apiUrl": "https://kya.vouched.id",
+      "cacheTtl": 300000
+    },
+    "fallback": {}
+  },
+  "audit": {
+    "enabled": true,
+    "includeProofHashes": false,
+    "includePayloads": false
+  },
+  "session": {
+    "timestampSkewSeconds": 120,
+    "ttlMinutes": 30
+  },
+  "platform": {
+    "type": "node",
+    "node": {
+      "server": {
+        "port": 3000,
+        "host": "0.0.0.0",
+        "cors": true,
+        "timeout": 30000
+      },
+      "storage": {
+        "type": "memory"
+      }
+    },
+    "cloudflare": {
+      "workers": {
+        "cpuMs": 50,
+        "memoryMb": 128
+      },
+      "kvNamespaces": [],
+      "environmentVariables": []
+    },
+    "vercel": {
+      "environmentVariables": [],
+      "edgeRuntime": {}
+    }
+  },
+  "metadata": {
+    "version": "1.0.0",
+    "lastUpdated": "",
+    "source": "dashboard",
+    "deploymentStatus": "inactive"
+  }
+}
+