@kya-os/contracts 1.5.4-canary.2 → 1.6.0

package/dist/consent/schemas.d.ts

@@ -6,7 +6,7 @@
  *
  * Related Spec: MCP-I Phase 0 Implementation Plan
  */
-import { z } from 'zod';
+import { z } from "zod";
 /**
  * Consent Branding Schema
  */
@@ -165,13 +165,14 @@ export type OAuthIdentity = z.infer<typeof oauthIdentitySchema>;
 /**
  * Consent Page Config Schema
  */
-export declare const consentPageConfigSchema: z.ZodObject<{
+export declare const consentPageConfigSchema: z.ZodEffects<z.ZodObject<{
     tool: z.ZodString;
     toolDescription: z.ZodString;
     scopes: z.ZodArray<z.ZodString, "many">;
     agentDid: z.ZodString;
     sessionId: z.ZodString;
     projectId: z.ZodString;
+    provider: z.ZodOptional<z.ZodString>;
     branding: z.ZodOptional<z.ZodObject<{
         primaryColor: z.ZodOptional<z.ZodString>;
         logoUrl: z.ZodOptional<z.ZodString>;
@@ -268,6 +269,16 @@ export declare const consentPageConfigSchema: z.ZodObject<{
     }>, "many">>;
     serverUrl: z.ZodString;
     autoClose: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Whether OAuth authorization is required immediately
+     * If true, the consent page will act as a landing page before redirecting
+     */
+    oauthRequired: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * The OAuth authorization URL to redirect to
+     * Required if oauthRequired is true
+     */
+    oauthUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
 }, "strip", z.ZodTypeAny, {
     tool: string;
     toolDescription: string;
@@ -276,6 +287,79 @@ export declare const consentPageConfigSchema: z.ZodObject<{
     sessionId: string;
     projectId: string;
     serverUrl: string;
+    provider?: string | undefined;
+    branding?: {
+        primaryColor?: string | undefined;
+        logoUrl?: string | undefined;
+        companyName?: string | undefined;
+        theme?: "light" | "dark" | "auto" | undefined;
+    } | undefined;
+    terms?: {
+        required: boolean;
+        text?: string | undefined;
+        url?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    customFields?: {
+        type: "text" | "textarea" | "checkbox" | "select";
+        required: boolean;
+        label: string;
+        name: string;
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        placeholder?: string | undefined;
+        pattern?: string | undefined;
+    }[] | undefined;
+    autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
+}, {
+    tool: string;
+    toolDescription: string;
+    scopes: string[];
+    agentDid: string;
+    sessionId: string;
+    projectId: string;
+    serverUrl: string;
+    provider?: string | undefined;
+    branding?: {
+        primaryColor?: string | undefined;
+        logoUrl?: string | undefined;
+        companyName?: string | undefined;
+        theme?: "light" | "dark" | "auto" | undefined;
+    } | undefined;
+    terms?: {
+        text?: string | undefined;
+        url?: string | undefined;
+        version?: string | undefined;
+        required?: boolean | undefined;
+    } | undefined;
+    customFields?: {
+        type: "text" | "textarea" | "checkbox" | "select";
+        required: boolean;
+        label: string;
+        name: string;
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        placeholder?: string | undefined;
+        pattern?: string | undefined;
+    }[] | undefined;
+    autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
+}>, {
+    tool: string;
+    toolDescription: string;
+    scopes: string[];
+    agentDid: string;
+    sessionId: string;
+    projectId: string;
+    serverUrl: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -301,6 +385,8 @@ export declare const consentPageConfigSchema: z.ZodObject<{
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }, {
     tool: string;
     toolDescription: string;
@@ -309,6 +395,7 @@ export declare const consentPageConfigSchema: z.ZodObject<{
     sessionId: string;
     projectId: string;
     serverUrl: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -334,6 +421,8 @@ export declare const consentPageConfigSchema: z.ZodObject<{
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }>;
 export type ConsentPageConfig = z.infer<typeof consentPageConfigSchema>;
 /**
@@ -355,9 +444,11 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
     termsVersion: z.ZodOptional<z.ZodString>;
     customFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>>;
     /**
-     * OAuth provider identity information (optional, can be null)
+     * OAuth provider identity information (optional)
      * Used to link OAuth accounts to persistent User DIDs
-     * Can be null when OAuth is not configured or user hasn't authenticated
+     *
+     * CRITICAL: Uses .nullish() to accept null, undefined, or OAuthIdentity
+     * This matches JSON parsing behavior where missing fields become null
      */
     oauth_identity: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         /**
@@ -658,6 +749,7 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
     sessionId: string;
     projectId: string;
     serverUrl: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -683,6 +775,8 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }, {
     tool: string;
     toolDescription: string;
@@ -691,6 +785,7 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
     sessionId: string;
     projectId: string;
     serverUrl: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -716,6 +811,8 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }>;
 /**
  * Validate a consent approval request

package/dist/consent/schemas.js

@@ -20,58 +20,79 @@ const zod_1 = require("zod");
 exports.consentBrandingSchema = zod_1.z.object({
     primaryColor: zod_1.z
         .string()
-        .regex(/^#[0-9A-Fa-f]{6}$/, 'Must be a valid hex color (e.g., #0066CC)')
+        .regex(/^#[0-9A-Fa-f]{6}$/, "Must be a valid hex color (e.g., #0066CC)")
         .optional(),
-    logoUrl: zod_1.z.string().url('Must be a valid URL').optional(),
-    companyName: zod_1.z.string().max(100, 'Company name must be 100 characters or less').optional(),
-    theme: zod_1.z.enum(['light', 'dark', 'auto']).optional(),
+    logoUrl: zod_1.z.string().url("Must be a valid URL").optional(),
+    companyName: zod_1.z
+        .string()
+        .max(100, "Company name must be 100 characters or less")
+        .optional(),
+    theme: zod_1.z.enum(["light", "dark", "auto"]).optional(),
 });
 /**
  * Consent Terms Schema
  */
 exports.consentTermsSchema = zod_1.z.object({
-    text: zod_1.z.string().max(10000, 'Terms text must be 10000 characters or less').optional(),
-    url: zod_1.z.string().url('Must be a valid URL').optional(),
-    version: zod_1.z.string().max(50, 'Version must be 50 characters or less').optional(),
+    text: zod_1.z
+        .string()
+        .max(10000, "Terms text must be 10000 characters or less")
+        .optional(),
+    url: zod_1.z.string().url("Must be a valid URL").optional(),
+    version: zod_1.z
+        .string()
+        .max(50, "Version must be 50 characters or less")
+        .optional(),
     required: zod_1.z.boolean().default(true),
 });
 /**
  * Consent Custom Field Option Schema
  */
 exports.consentCustomFieldOptionSchema = zod_1.z.object({
-    value: zod_1.z.string().max(100, 'Option value must be 100 characters or less'),
-    label: zod_1.z.string().max(100, 'Option label must be 100 characters or less'),
+    value: zod_1.z.string().max(100, "Option value must be 100 characters or less"),
+    label: zod_1.z.string().max(100, "Option label must be 100 characters or less"),
 });
 /**
  * Consent Custom Field Schema
  */
-exports.consentCustomFieldSchema = zod_1.z.object({
+exports.consentCustomFieldSchema = zod_1.z
+    .object({
     name: zod_1.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: zod_1.z.string().min(1, 'Field label is required').max(100, 'Field label must be 100 characters or less'),
-    type: zod_1.z.enum(['text', 'textarea', 'checkbox', 'select']),
+        .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: zod_1.z
+        .string()
+        .min(1, "Field label is required")
+        .max(100, "Field label must be 100 characters or less"),
+    type: zod_1.z.enum(["text", "textarea", "checkbox", "select"]),
     required: zod_1.z.boolean(),
-    placeholder: zod_1.z.string().max(200, 'Placeholder must be 200 characters or less').optional(),
+    placeholder: zod_1.z
+        .string()
+        .max(200, "Placeholder must be 200 characters or less")
+        .optional(),
     options: zod_1.z
         .array(exports.consentCustomFieldOptionSchema)
-        .min(1, 'Select fields must have at least one option')
+        .min(1, "Select fields must have at least one option")
+        .optional(),
+    pattern: zod_1.z
+        .string()
+        .max(500, "Pattern must be 500 characters or less")
         .optional(),
-    pattern: zod_1.z.string().max(500, 'Pattern must be 500 characters or less').optional(),
-}).refine((data) => {
+})
+    .refine((data) => {
     // Select fields must have options
-    if (data.type === 'select' && (!data.options || data.options.length === 0)) {
+    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) {
+    if (data.type !== "select" && data.options) {
         return false;
     }
     return true;
 }, {
-    message: 'Select fields must have options, and non-select fields must not have options',
+    message: "Select fields must have options, and non-select fields must not have options",
 });
 /**
  * OAuth Identity Schema
@@ -83,48 +104,89 @@ exports.oauthIdentitySchema = zod_1.z.object({
     /**
      * OAuth provider name (e.g., "google", "github", "microsoft")
      */
-    provider: zod_1.z.string()
-        .min(1, 'Provider is required')
-        .max(50, 'Provider name must be 50 characters or less'),
+    provider: zod_1.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: zod_1.z.string()
-        .min(1, 'Subject is required')
-        .max(255, 'Subject must be 255 characters or less'),
+    subject: zod_1.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: zod_1.z.string()
-        .email('Must be a valid email address')
-        .max(255, 'Email must be 255 characters or less')
+    email: zod_1.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: zod_1.z.string()
-        .max(255, 'Name must be 255 characters or less')
-        .optional(),
+    name: zod_1.z.string().max(255, "Name must be 255 characters or less").optional(),
 });
 /**
  * Consent Page Config Schema
  */
-exports.consentPageConfigSchema = zod_1.z.object({
-    tool: zod_1.z.string().min(1, 'Tool name is required'),
-    toolDescription: zod_1.z.string().max(500, 'Tool description must be 500 characters or less'),
-    scopes: zod_1.z.array(zod_1.z.string()).min(0, 'Scopes array cannot be negative'),
-    agentDid: zod_1.z.string().min(1, 'Agent DID is required'),
-    sessionId: zod_1.z.string().min(1, 'Session ID is required'),
-    projectId: zod_1.z.string().min(1, 'Project ID is required'),
+exports.consentPageConfigSchema = zod_1.z
+    .object({
+    tool: zod_1.z.string().min(1, "Tool name is required"),
+    toolDescription: zod_1.z
+        .string()
+        .max(500, "Tool description must be 500 characters or less"),
+    scopes: zod_1.z.array(zod_1.z.string()).min(0, "Scopes array cannot be negative"),
+    agentDid: zod_1.z.string().min(1, "Agent DID is required"),
+    sessionId: zod_1.z.string().min(1, "Session ID is required"),
+    projectId: zod_1.z.string().min(1, "Project ID is required"),
+    provider: zod_1.z.string().optional(), // Phase 2: OAuth provider name (e.g., "github", "google")
     branding: exports.consentBrandingSchema.optional(),
     terms: exports.consentTermsSchema.optional(),
     customFields: zod_1.z
         .array(exports.consentCustomFieldSchema)
-        .max(10, 'Maximum 10 custom fields allowed')
+        .max(10, "Maximum 10 custom fields allowed")
         .optional(),
-    serverUrl: zod_1.z.string().url('Server URL must be a valid URL'),
+    serverUrl: zod_1.z.string().url("Server URL must be a valid URL"),
     autoClose: zod_1.z.boolean().optional(),
+    /**
+     * Whether OAuth authorization is required immediately
+     * If true, the consent page will act as a landing page before redirecting
+     */
+    oauthRequired: zod_1.z.boolean().optional(),
+    /**
+     * The OAuth authorization URL to redirect to
+     * Required if oauthRequired is true
+     */
+    oauthUrl: zod_1.z
+        .union([
+        zod_1.z.string().url(),
+        zod_1.z.literal(""), // Allow empty string to catch it in refine with better error
+    ])
+        .optional(),
+})
+    .superRefine((data, ctx) => {
+    // If oauthRequired is true, oauthUrl must be provided and non-empty
+    if (data.oauthRequired === true) {
+        if (data.oauthUrl === undefined || data.oauthUrl === "") {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "oauthUrl is required when oauthRequired is true",
+                path: ["oauthUrl"],
+            });
+            return;
+        }
+    }
+    // If oauthUrl is provided (not undefined), it must be a valid URL (not empty)
+    if (data.oauthUrl !== undefined && data.oauthUrl === "") {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "oauthUrl must be a valid URL",
+            path: ["oauthUrl"],
+        });
+    }
 });
 /**
  * Consent Approval Request Schema
@@ -136,23 +198,24 @@ exports.consentPageConfigSchema = zod_1.z.object({
  * - user_did: Optional User DID for persistent identity (if already known)
  */
 exports.consentApprovalRequestSchema = zod_1.z.object({
-    tool: zod_1.z.string().min(1, 'Tool name is required'),
-    scopes: zod_1.z.array(zod_1.z.string()).min(0, 'Scopes array cannot be negative'),
-    agent_did: zod_1.z.string().min(1, 'Agent DID is required'),
-    session_id: zod_1.z.string().min(1, 'Session ID is required'),
-    project_id: zod_1.z.string().min(1, 'Project ID is required'),
+    tool: zod_1.z.string().min(1, "Tool name is required"),
+    scopes: zod_1.z.array(zod_1.z.string()).min(0, "Scopes array cannot be negative"),
+    agent_did: zod_1.z.string().min(1, "Agent DID is required"),
+    session_id: zod_1.z.string().min(1, "Session ID is required"),
+    project_id: zod_1.z.string().min(1, "Project ID is required"),
     termsAccepted: zod_1.z.boolean(),
-    termsVersion: zod_1.z.string()
-        .max(50, 'Terms version must be 50 characters or less')
-        .optional(),
-    customFields: zod_1.z
-        .record(zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()]))
+    termsVersion: zod_1.z
+        .string()
+        .max(50, "Terms version must be 50 characters or less")
         .optional(),
+    customFields: zod_1.z.record(zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])).optional(),
     // Phase 4: OAuth identity linking
     /**
-     * OAuth provider identity information (optional, can be null)
+     * OAuth provider identity information (optional)
      * Used to link OAuth accounts to persistent User DIDs
-     * Can be null when OAuth is not configured or user hasn't authenticated
+     *
+     * CRITICAL: Uses .nullish() to accept null, undefined, or OAuthIdentity
+     * This matches JSON parsing behavior where missing fields become null
      */
     oauth_identity: exports.oauthIdentitySchema.nullish(),
     /**
@@ -160,21 +223,24 @@ exports.consentApprovalRequestSchema = zod_1.z.object({
      * If provided, represents the persistent User DID for this user
      * Format: did:key:... or did:web:...
      */
-    user_did: zod_1.z.string()
-        .regex(/^did:/, 'Must be a valid DID format (starting with did:)')
-        .max(500, 'DID must be 500 characters or less')
+    user_did: zod_1.z
+        .string()
+        .regex(/^did:/, "Must be a valid DID format (starting with did:)")
+        .max(500, "DID must be 500 characters or less")
         .optional(),
 });
 /**
  * Consent Approval Response Schema
  */
-exports.consentApprovalResponseSchema = zod_1.z.object({
+exports.consentApprovalResponseSchema = zod_1.z
+    .object({
     success: zod_1.z.boolean(),
     delegation_id: zod_1.z.string().min(1).optional(),
     delegation_token: zod_1.z.string().min(1).optional(),
     error: zod_1.z.string().optional(),
     error_code: zod_1.z.string().optional(),
-}).refine((data) => {
+})
+    .refine((data) => {
     // If success is true, must have delegation_id and delegation_token
     if (data.success) {
         return !!data.delegation_id && !!data.delegation_token;
@@ -182,7 +248,7 @@ exports.consentApprovalResponseSchema = zod_1.z.object({
     // 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',
+    message: "Successful responses must include delegation_id and delegation_token. Failed responses must include error or error_code",
 });
 /**
  * Consent Config Schema
@@ -192,14 +258,21 @@ exports.consentConfigSchema = zod_1.z.object({
     terms: exports.consentTermsSchema.optional(),
     customFields: zod_1.z
         .array(exports.consentCustomFieldSchema)
-        .max(10, 'Maximum 10 custom fields allowed')
+        .max(10, "Maximum 10 custom fields allowed")
         .optional(),
-    ui: zod_1.z.object({
-        theme: zod_1.z.enum(['light', 'dark', 'auto']).optional(),
+    ui: zod_1.z
+        .object({
+        theme: zod_1.z.enum(["light", "dark", "auto"]).optional(),
         popupEnabled: zod_1.z.boolean().optional(),
         autoClose: zod_1.z.boolean().optional(),
-        autoCloseDelay: zod_1.z.number().int().positive().max(60000, 'Auto-close delay must be 60000ms or less').optional(),
-    }).optional(),
+        autoCloseDelay: zod_1.z
+            .number()
+            .int()
+            .positive()
+            .max(60000, "Auto-close delay must be 60000ms or less")
+            .optional(),
+    })
+        .optional(),
 });
 /**
  * Validation Helpers