@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.8117ac2

package/dist/utils/grantValidation.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/grantValidation.ts"],"sourcesContent":["import { Address, getAddress } from \"viem\";\nimport Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport type { GrantFile } from \"../types/permissions\";\nimport grantFileSchema from \"../schemas/grantFile.schema.json\";\n\n/**\n * Base error class for grant validation failures\n *\n * @category Permissions\n */\nexport class GrantValidationError extends Error {\n  constructor(\n    message: string,\n    public details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.name = \"GrantValidationError\";\n  }\n}\n\n/**\n * Error thrown when a grant has expired\n *\n * @category Permissions\n */\nexport class GrantExpiredError extends GrantValidationError {\n  constructor(\n    message: string,\n    public expires: number,\n    public currentTime: number,\n  ) {\n    super(message, { expires, currentTime });\n    this.name = \"GrantExpiredError\";\n  }\n}\n\n/**\n * Error thrown when grantee doesn't match requesting address\n *\n * @category Permissions\n */\nexport class GranteeMismatchError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantee: Address,\n    public requestingAddress: Address,\n  ) {\n    super(message, { grantee, requestingAddress });\n    this.name = \"GranteeMismatchError\";\n  }\n}\n\n/**\n * Error thrown when operation is not allowed by grant\n *\n * @category Permissions\n */\nexport class OperationNotAllowedError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantedOperation: string,\n    public requestedOperation: string,\n  ) {\n    super(message, { grantedOperation, requestedOperation });\n    this.name = \"OperationNotAllowedError\";\n  }\n}\n\n/**\n * Error thrown when grant file structure is invalid\n *\n * @category Permissions\n */\nexport class GrantSchemaError extends GrantValidationError {\n  constructor(\n    message: string,\n    public schemaErrors: unknown[],\n    public invalidData: unknown,\n  ) {\n    super(message, { errors: schemaErrors, data: invalidData });\n    this.name = \"GrantSchemaError\";\n  }\n}\n\n/**\n * Ajv instance for grant file validation with draft 2020-12 support\n */\nconst ajv = new Ajv({\n  strict: true,\n  removeAdditional: false,\n  useDefaults: false,\n  coerceTypes: false,\n});\n\n// Add format validators (email, date, etc.)\naddFormats(ajv);\n\n/**\n * Compiled grant file schema validator\n */\nconst validateGrantFileSchema: ValidateFunction = ajv.compile(grantFileSchema);\n\n/**\n * Options for grant validation\n *\n * @category Permissions\n */\nexport interface GrantValidationOptions {\n  /** Enable JSON schema validation (default: true) */\n  schema?: boolean;\n  /** Grantee address to validate access for */\n  grantee?: Address;\n  /** Operation to validate permission for */\n  operation?: string;\n  /** Override current time for expiry checking (Unix timestamp) */\n  currentTime?: number;\n  /** Return detailed results instead of throwing (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Detailed validation result\n *\n * @category Permissions\n */\nexport interface GrantValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors encountered */\n  errors: Array<{\n    type: \"schema\" | \"business\";\n    field?: string;\n    message: string;\n    error?: Error;\n  }>;\n  /** The validated grant file (if validation passed) */\n  grant?: GrantFile;\n}\n\n/**\n * Validates a grant file with comprehensive schema and business rule checking.\n *\n * This function provides flexible validation with TypeScript overloads:\n * - When `throwOnError` is false (or `{ throwOnError: false }`), returns a detailed validation result\n * - When `throwOnError` is true (default), throws specific errors or returns the validated grant\n *\n * @param data - The grant file data to validate (unknown type for safety)\n * @param options - Validation options including grantee, operation, files, etc.\n * @returns Either a GrantFile (when throwing) or GrantValidationResult (when not throwing)\n * @throws {GrantSchemaError} When the grant file structure is invalid\n * @throws {GrantExpiredError} When the grant has expired\n * @throws {GranteeMismatchError} When the grantee doesn't match the requesting address\n * @throws {OperationNotAllowedError} When the requested operation is not allowed\n * @example\n * ```typescript\n * // Throwing mode (default) - returns GrantFile or throws\n * const grant = validateGrant(data, {\n *   grantee: '0x123...',\n *   operation: 'llm_inference',\n * });\n *\n * // Non-throwing mode - returns validation result\n * const result = validateGrant(data, {\n *   grantee: '0x123...',\n *   throwOnError: false\n * });\n * if (result.valid) {\n *   console.log('Grant is valid:', result.grant);\n * } else {\n *   console.log('Validation errors:', result.errors);\n * }\n * ```\n */\n\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions & { throwOnError: false },\n): GrantValidationResult;\n\nexport function validateGrant(\n  data: unknown,\n  options?:\n    | Omit<GrantValidationOptions, \"throwOnError\">\n    | (GrantValidationOptions & { throwOnError?: true }),\n): GrantFile;\n\n/**\n * Implementation function for grant validation with flexible return types\n *\n * @param data - The grant file data to validate\n * @param options - Validation configuration options\n * @returns Either a GrantFile or GrantValidationResult depending on throwOnError setting\n */\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions = {},\n): GrantFile | GrantValidationResult {\n  const {\n    schema = true,\n    grantee,\n    operation,\n    currentTime,\n    throwOnError = true,\n  } = options;\n\n  const errors: GrantValidationResult[\"errors\"] = [];\n  let grant: GrantFile | undefined;\n\n  // 1. Schema Validation\n  if (schema) {\n    try {\n      if (validateGrantFileSchema(data)) {\n        grant = data as GrantFile;\n      } else {\n        throw new GrantValidationError(\"Invalid grant file schema\");\n      }\n    } catch (error) {\n      if (error instanceof GrantValidationError) {\n        const schemaError = new GrantSchemaError(\n          error.message,\n          Array.isArray(error.details?.errors) ? error.details.errors : [],\n          data,\n        );\n        errors.push({\n          type: \"schema\",\n          message: error.message,\n          error: schemaError,\n        });\n      } else {\n        errors.push({\n          type: \"schema\",\n          message: `Schema validation failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  } else {\n    // Minimal type assertion if schema validation is skipped\n    grant = data as GrantFile;\n  }\n\n  // 2. Business Logic Validation (only if we have a valid grant)\n  if (grant) {\n    // Check grantee access\n    if (grantee) {\n      try {\n        validateGranteeAccess(grant, grantee);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n\n    // Check expiration\n    try {\n      validateGrantExpiry(grant, currentTime);\n    } catch (error) {\n      const field = extractFieldFromBusinessError(error);\n      errors.push({\n        type: \"business\",\n        field,\n        message:\n          error instanceof Error\n            ? error.message\n            : \"Unknown business rule error\",\n        error: error instanceof Error ? error : new Error(\"Unknown error\"),\n      });\n    }\n\n    // Check operation access\n    if (operation) {\n      try {\n        validateOperationAccess(grant, operation);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  }\n\n  // 3. Return Results\n  if (errors.length > 0) {\n    if (throwOnError) {\n      // Throw the most specific error we have\n      const firstError = errors[0];\n      if (firstError.error) {\n        throw firstError.error;\n      } else {\n        const combinedMessage = errors.map((e) => e.message).join(\"; \");\n        throw new GrantValidationError(\n          `Grant validation failed: ${combinedMessage}`,\n          { errors, data },\n        );\n      }\n    }\n\n    return { valid: false, errors, grant };\n  }\n\n  if (throwOnError) {\n    return grant as GrantFile;\n  } else {\n    return { valid: true, errors: [], grant: grant as GrantFile };\n  }\n}\n\n/**\n * Helper function to extract field name from business validation errors\n *\n * @param error - The validation error to extract field information from\n * @returns The field name associated with the error, or undefined if not applicable\n */\nfunction extractFieldFromBusinessError(error: unknown): string | undefined {\n  if (error instanceof GrantExpiredError) return \"expires\";\n  if (error instanceof GranteeMismatchError) return \"grantee\";\n  if (error instanceof OperationNotAllowedError) return \"operation\";\n  return undefined;\n}\n\n/**\n * Validates that a grant file allows access for a specific grantee\n *\n * @param grantFile - The grant file to validate access for\n * @param requestingAddress - The address requesting access to check against the grantee\n */\nexport function validateGranteeAccess(\n  grantFile: GrantFile,\n  requestingAddress: Address,\n): void {\n  const normalizedGrantee = getAddress(grantFile.grantee);\n  const normalizedRequesting = getAddress(requestingAddress);\n\n  if (normalizedGrantee !== normalizedRequesting) {\n    throw new GranteeMismatchError(\n      \"Permission denied: requesting address does not match grantee\",\n      grantFile.grantee,\n      requestingAddress,\n    );\n  }\n}\n\n/**\n * Validates that a grant has not expired (if expiry is set)\n *\n * @param grantFile - The grant file to check expiration for\n * @param currentTime - Optional override for current time (Unix timestamp)\n */\nexport function validateGrantExpiry(\n  grantFile: GrantFile,\n  currentTime?: number,\n): void {\n  if (grantFile.expires) {\n    const now = currentTime || Math.floor(Date.now() / 1000); // Current Unix timestamp\n\n    if (now > grantFile.expires) {\n      throw new GrantExpiredError(\n        \"Permission denied: grant has expired\",\n        grantFile.expires,\n        now,\n      );\n    }\n  }\n}\n\n/**\n * Validates that a grant allows a specific operation\n *\n * @param grantFile - The grant file to validate operation access for\n * @param requestedOperation - The operation being requested to validate against the grant\n */\nexport function validateOperationAccess(\n  grantFile: GrantFile,\n  requestedOperation: string,\n): void {\n  if (grantFile.operation !== requestedOperation) {\n    throw new OperationNotAllowedError(\n      \"Permission denied: operation not allowed by grant\",\n      grantFile.operation,\n      requestedOperation,\n    );\n  }\n}\n"],"mappings":"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","names":["Ajv","addFormats","grantFileSchema"]}
+{"version":3,"sources":["../../src/utils/grantValidation.ts"],"sourcesContent":["/**\n * Provides comprehensive validation for permission grant files.\n *\n * @remarks\n * This module implements multi-layer validation for grant files including\n * JSON schema validation, business rule checking, expiration verification,\n * and access control validation. It provides both throwing and non-throwing\n * modes for flexible error handling.\n *\n * @category Permissions\n * @module utils/grantValidation\n */\n\nimport type { Address } from \"viem\";\nimport { getAddress } from \"viem\";\nimport Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport type { GrantFile } from \"../types/permissions\";\nimport grantFileSchema from \"../schemas/grantFile.schema.json\";\n\n/**\n * Indicates a general grant validation failure.\n *\n * @remarks\n * Base class for all grant validation errors. Provides structured\n * error details for debugging and recovery.\n *\n * @category Permissions\n */\nexport class GrantValidationError extends Error {\n  constructor(\n    message: string,\n    public details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.name = \"GrantValidationError\";\n  }\n}\n\n/**\n * Indicates that a grant has expired and is no longer valid.\n *\n * @remarks\n * Thrown when attempting to use a grant past its expiration timestamp.\n * Includes both the expiration time and current time for debugging.\n *\n * @category Permissions\n */\nexport class GrantExpiredError extends GrantValidationError {\n  constructor(\n    message: string,\n    public expires: number,\n    public currentTime: number,\n  ) {\n    super(message, { expires, currentTime });\n    this.name = \"GrantExpiredError\";\n  }\n}\n\n/**\n * Indicates that the requesting address doesn't match the grant's grantee.\n *\n * @remarks\n * Thrown when a user attempts to use a grant that was issued to a\n * different address. This prevents unauthorized use of permissions.\n *\n * @category Permissions\n */\nexport class GranteeMismatchError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantee: Address,\n    public requestingAddress: Address,\n  ) {\n    super(message, { grantee, requestingAddress });\n    this.name = \"GranteeMismatchError\";\n  }\n}\n\n/**\n * Indicates that the requested operation is not allowed by the grant.\n *\n * @remarks\n * Thrown when attempting an operation that differs from what the\n * grant authorizes. Includes both granted and requested operations.\n *\n * @category Permissions\n */\nexport class OperationNotAllowedError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantedOperation: string,\n    public requestedOperation: string,\n  ) {\n    super(message, { grantedOperation, requestedOperation });\n    this.name = \"OperationNotAllowedError\";\n  }\n}\n\n/**\n * Indicates that the grant file structure violates the JSON schema.\n *\n * @remarks\n * Thrown when a grant file doesn't conform to the expected schema.\n * Includes detailed schema validation errors and the invalid data.\n *\n * @category Permissions\n */\nexport class GrantSchemaError extends GrantValidationError {\n  constructor(\n    message: string,\n    public schemaErrors: unknown[],\n    public invalidData: unknown,\n  ) {\n    super(message, { errors: schemaErrors, data: invalidData });\n    this.name = \"GrantSchemaError\";\n  }\n}\n\n/**\n * Ajv instance configured for strict grant file validation.\n *\n * @internal\n */\nconst ajv = new Ajv({\n  strict: true,\n  removeAdditional: false,\n  useDefaults: false,\n  coerceTypes: false,\n});\n\n// Add format validators (email, date, etc.)\naddFormats(ajv);\n\n/**\n * Pre-compiled grant file schema validator for performance.\n *\n * @internal\n */\nconst validateGrantFileSchema: ValidateFunction = ajv.compile(grantFileSchema);\n\n/**\n * Configures grant validation behavior and scope.\n *\n * @remarks\n * Controls which validations to perform and how to handle errors.\n * Allows selective validation of specific aspects of a grant.\n *\n * @category Permissions\n */\nexport interface GrantValidationOptions {\n  /** Enable JSON schema validation (default: true) */\n  schema?: boolean;\n  /** Grantee address to validate access for */\n  grantee?: Address;\n  /** Operation to validate permission for */\n  operation?: string;\n  /** Override current time for expiry checking (Unix timestamp) */\n  currentTime?: number;\n  /** Return detailed results instead of throwing (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Represents the detailed result of grant validation.\n *\n * @remarks\n * Provides comprehensive validation results including all errors\n * encountered during validation. Used in non-throwing mode.\n *\n * @category Permissions\n */\nexport interface GrantValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors encountered */\n  errors: Array<{\n    type: \"schema\" | \"business\";\n    field?: string;\n    message: string;\n    error?: Error;\n  }>;\n  /** The validated grant file (if validation passed) */\n  grant?: GrantFile;\n}\n\n/**\n * Validates a grant file with comprehensive schema and business rule checking.\n *\n * This function provides flexible validation with TypeScript overloads:\n * - When `throwOnError` is false (or `{ throwOnError: false }`), returns a detailed validation result\n * - When `throwOnError` is true (default), throws specific errors or returns the validated grant\n *\n * @param data - The grant file data to validate (unknown type for safety)\n * @param options - Validation options including grantee, operation, files, etc.\n * @returns Either a GrantFile (when throwing) or GrantValidationResult (when not throwing)\n * @throws {GrantSchemaError} When the grant file structure is invalid\n * @throws {GrantExpiredError} When the grant has expired\n * @throws {GranteeMismatchError} When the grantee doesn't match the requesting address\n * @throws {OperationNotAllowedError} When the requested operation is not allowed\n * @example\n * ```typescript\n * // Throwing mode (default) - returns GrantFile or throws\n * const grant = validateGrant(data, {\n *   grantee: '0x123...',\n *   operation: 'llm_inference',\n * });\n *\n * // Non-throwing mode - returns validation result\n * const result = validateGrant(data, {\n *   grantee: '0x123...',\n *   throwOnError: false\n * });\n * if (result.valid) {\n *   console.log('Grant is valid:', result.grant);\n * } else {\n *   console.log('Validation errors:', result.errors);\n * }\n * ```\n */\n\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions & { throwOnError: false },\n): GrantValidationResult;\n\nexport function validateGrant(\n  data: unknown,\n  options?:\n    | Omit<GrantValidationOptions, \"throwOnError\">\n    | (GrantValidationOptions & { throwOnError?: true }),\n): GrantFile;\n\n/** @internal */\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions = {},\n): GrantFile | GrantValidationResult {\n  const {\n    schema = true,\n    grantee,\n    operation,\n    currentTime,\n    throwOnError = true,\n  } = options;\n\n  const errors: GrantValidationResult[\"errors\"] = [];\n  let grant: GrantFile | undefined;\n\n  // 1. Schema Validation\n  if (schema) {\n    try {\n      if (validateGrantFileSchema(data)) {\n        grant = data as GrantFile;\n      } else {\n        throw new GrantValidationError(\"Invalid grant file schema\");\n      }\n    } catch (error) {\n      if (error instanceof GrantValidationError) {\n        const schemaError = new GrantSchemaError(\n          error.message,\n          Array.isArray(error.details?.errors) ? error.details.errors : [],\n          data,\n        );\n        errors.push({\n          type: \"schema\",\n          message: error.message,\n          error: schemaError,\n        });\n      } else {\n        errors.push({\n          type: \"schema\",\n          message: `Schema validation failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  } else {\n    // Minimal type assertion if schema validation is skipped\n    grant = data as GrantFile;\n  }\n\n  // 2. Business Logic Validation (only if we have a valid grant)\n  if (grant) {\n    // Check grantee access\n    if (grantee) {\n      try {\n        validateGranteeAccess(grant, grantee);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n\n    // Check expiration\n    try {\n      validateGrantExpiry(grant, currentTime);\n    } catch (error) {\n      const field = extractFieldFromBusinessError(error);\n      errors.push({\n        type: \"business\",\n        field,\n        message:\n          error instanceof Error\n            ? error.message\n            : \"Unknown business rule error\",\n        error: error instanceof Error ? error : new Error(\"Unknown error\"),\n      });\n    }\n\n    // Check operation access\n    if (operation) {\n      try {\n        validateOperationAccess(grant, operation);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  }\n\n  // 3. Return Results\n  if (errors.length > 0) {\n    if (throwOnError) {\n      // Throw the most specific error we have\n      const firstError = errors[0];\n      if (firstError.error) {\n        throw firstError.error;\n      } else {\n        const combinedMessage = errors.map((e) => e.message).join(\"; \");\n        throw new GrantValidationError(\n          `Grant validation failed: ${combinedMessage}`,\n          { errors, data },\n        );\n      }\n    }\n\n    return { valid: false, errors, grant };\n  }\n\n  if (throwOnError) {\n    return grant as GrantFile;\n  } else {\n    return { valid: true, errors: [], grant: grant as GrantFile };\n  }\n}\n\n/**\n * Extracts the field name from business validation errors for reporting.\n *\n * @param error - The validation error to analyze\n * @returns The field name associated with the error, or undefined\n *\n * @internal\n */\nfunction extractFieldFromBusinessError(error: unknown): string | undefined {\n  if (error instanceof GrantExpiredError) return \"expires\";\n  if (error instanceof GranteeMismatchError) return \"grantee\";\n  if (error instanceof OperationNotAllowedError) return \"operation\";\n  return undefined;\n}\n\n/**\n * Validates that a grant allows access for the requesting address.\n *\n * @param grantFile - The grant file to validate.\n *   Obtain from permission operations or server responses.\n * @param requestingAddress - The address requesting access.\n *   Typically the current wallet address.\n *\n * @throws {GranteeMismatchError} If addresses don't match.\n *   Ensure using the correct wallet that received the grant.\n *\n * @example\n * ```typescript\n * validateGranteeAccess(grantFile, walletAddress);\n * // Throws if walletAddress doesn't match grantFile.grantee\n * ```\n *\n * @category Permissions\n */\nexport function validateGranteeAccess(\n  grantFile: GrantFile,\n  requestingAddress: Address,\n): void {\n  const normalizedGrantee = getAddress(grantFile.grantee);\n  const normalizedRequesting = getAddress(requestingAddress);\n\n  if (normalizedGrantee !== normalizedRequesting) {\n    throw new GranteeMismatchError(\n      \"Permission denied: requesting address does not match grantee\",\n      grantFile.grantee,\n      requestingAddress,\n    );\n  }\n}\n\n/**\n * Validates that a grant has not expired.\n *\n * @param grantFile - The grant file to check.\n *   Must include expiry timestamp if time-limited.\n * @param currentTime - Optional time override for testing.\n *   Unix timestamp in seconds. Defaults to current time.\n *\n * @throws {GrantExpiredError} If grant has expired.\n *   Request a new grant from the data owner.\n *\n * @example\n * ```typescript\n * validateGrantExpiry(grantFile);\n * // Throws if current time > grantFile.expires\n * ```\n *\n * @category Permissions\n */\nexport function validateGrantExpiry(\n  grantFile: GrantFile,\n  currentTime?: number,\n): void {\n  if (grantFile.expires) {\n    const now =\n      currentTime !== undefined ? currentTime : Math.floor(Date.now() / 1000); // Current Unix timestamp\n\n    if (now > grantFile.expires) {\n      throw new GrantExpiredError(\n        \"Permission denied: grant has expired\",\n        grantFile.expires,\n        now,\n      );\n    }\n  }\n}\n\n/**\n * Validates that a grant authorizes the requested operation.\n *\n * @param grantFile - The grant file to check.\n *   Contains the authorized operation.\n * @param requestedOperation - The operation to validate.\n *   Must match the grant's operation exactly.\n *\n * @throws {OperationNotAllowedError} If operations don't match.\n *   Request a grant for the specific operation needed.\n *\n * @example\n * ```typescript\n * validateOperationAccess(grantFile, 'llm_inference');\n * // Throws if grantFile.operation !== 'llm_inference'\n * ```\n *\n * @category Permissions\n */\nexport function validateOperationAccess(\n  grantFile: GrantFile,\n  requestedOperation: string,\n): void {\n  if (grantFile.operation !== requestedOperation) {\n    throw new OperationNotAllowedError(\n      \"Permission denied: operation not allowed by grant\",\n      grantFile.operation,\n      requestedOperation,\n    );\n  }\n}\n"],"mappings":"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","names":["Ajv","addFormats","grantFileSchema"]}

package/dist/utils/grantValidation.d.ts

@@ -1,61 +1,96 @@
-import { Address } from 'viem';
-import { GrantFile } from '../types/permissions.js';
-
 /**
- * Base error class for grant validation failures
+ * Provides comprehensive validation for permission grant files.
+ *
+ * @remarks
+ * This module implements multi-layer validation for grant files including
+ * JSON schema validation, business rule checking, expiration verification,
+ * and access control validation. It provides both throwing and non-throwing
+ * modes for flexible error handling.
  *
  * @category Permissions
+ * @module utils/grantValidation
  */
-declare class GrantValidationError extends Error {
+import type { Address } from "viem";
+import type { GrantFile } from "../types/permissions";
+/**
+ * Indicates a general grant validation failure.
+ *
+ * @remarks
+ * Base class for all grant validation errors. Provides structured
+ * error details for debugging and recovery.
+ *
+ * @category Permissions
+ */
+export declare class GrantValidationError extends Error {
     details?: Record<string, unknown> | undefined;
     constructor(message: string, details?: Record<string, unknown> | undefined);
 }
 /**
- * Error thrown when a grant has expired
+ * Indicates that a grant has expired and is no longer valid.
+ *
+ * @remarks
+ * Thrown when attempting to use a grant past its expiration timestamp.
+ * Includes both the expiration time and current time for debugging.
  *
  * @category Permissions
  */
-declare class GrantExpiredError extends GrantValidationError {
+export declare class GrantExpiredError extends GrantValidationError {
     expires: number;
     currentTime: number;
     constructor(message: string, expires: number, currentTime: number);
 }
 /**
- * Error thrown when grantee doesn't match requesting address
+ * Indicates that the requesting address doesn't match the grant's grantee.
+ *
+ * @remarks
+ * Thrown when a user attempts to use a grant that was issued to a
+ * different address. This prevents unauthorized use of permissions.
  *
  * @category Permissions
  */
-declare class GranteeMismatchError extends GrantValidationError {
+export declare class GranteeMismatchError extends GrantValidationError {
     grantee: Address;
     requestingAddress: Address;
     constructor(message: string, grantee: Address, requestingAddress: Address);
 }
 /**
- * Error thrown when operation is not allowed by grant
+ * Indicates that the requested operation is not allowed by the grant.
+ *
+ * @remarks
+ * Thrown when attempting an operation that differs from what the
+ * grant authorizes. Includes both granted and requested operations.
  *
  * @category Permissions
  */
-declare class OperationNotAllowedError extends GrantValidationError {
+export declare class OperationNotAllowedError extends GrantValidationError {
     grantedOperation: string;
     requestedOperation: string;
     constructor(message: string, grantedOperation: string, requestedOperation: string);
 }
 /**
- * Error thrown when grant file structure is invalid
+ * Indicates that the grant file structure violates the JSON schema.
+ *
+ * @remarks
+ * Thrown when a grant file doesn't conform to the expected schema.
+ * Includes detailed schema validation errors and the invalid data.
  *
  * @category Permissions
  */
-declare class GrantSchemaError extends GrantValidationError {
+export declare class GrantSchemaError extends GrantValidationError {
     schemaErrors: unknown[];
     invalidData: unknown;
     constructor(message: string, schemaErrors: unknown[], invalidData: unknown);
 }
 /**
- * Options for grant validation
+ * Configures grant validation behavior and scope.
+ *
+ * @remarks
+ * Controls which validations to perform and how to handle errors.
+ * Allows selective validation of specific aspects of a grant.
  *
  * @category Permissions
  */
-interface GrantValidationOptions {
+export interface GrantValidationOptions {
     /** Enable JSON schema validation (default: true) */
     schema?: boolean;
     /** Grantee address to validate access for */
@@ -68,11 +103,15 @@ interface GrantValidationOptions {
     throwOnError?: boolean;
 }
 /**
- * Detailed validation result
+ * Represents the detailed result of grant validation.
+ *
+ * @remarks
+ * Provides comprehensive validation results including all errors
+ * encountered during validation. Used in non-throwing mode.
  *
  * @category Permissions
  */
-interface GrantValidationResult {
+export interface GrantValidationResult {
     /** Whether validation passed */
     valid: boolean;
     /** Validation errors encountered */
@@ -119,32 +158,69 @@ interface GrantValidationResult {
  * }
  * ```
  */
-declare function validateGrant(data: unknown, options: GrantValidationOptions & {
+export declare function validateGrant(data: unknown, options: GrantValidationOptions & {
     throwOnError: false;
 }): GrantValidationResult;
-declare function validateGrant(data: unknown, options?: Omit<GrantValidationOptions, "throwOnError"> | (GrantValidationOptions & {
+export declare function validateGrant(data: unknown, options?: Omit<GrantValidationOptions, "throwOnError"> | (GrantValidationOptions & {
     throwOnError?: true;
 })): GrantFile;
 /**
- * Validates that a grant file allows access for a specific grantee
+ * Validates that a grant allows access for the requesting address.
+ *
+ * @param grantFile - The grant file to validate.
+ *   Obtain from permission operations or server responses.
+ * @param requestingAddress - The address requesting access.
+ *   Typically the current wallet address.
  *
- * @param grantFile - The grant file to validate access for
- * @param requestingAddress - The address requesting access to check against the grantee
+ * @throws {GranteeMismatchError} If addresses don't match.
+ *   Ensure using the correct wallet that received the grant.
+ *
+ * @example
+ * ```typescript
+ * validateGranteeAccess(grantFile, walletAddress);
+ * // Throws if walletAddress doesn't match grantFile.grantee
+ * ```
+ *
+ * @category Permissions
  */
-declare function validateGranteeAccess(grantFile: GrantFile, requestingAddress: Address): void;
+export declare function validateGranteeAccess(grantFile: GrantFile, requestingAddress: Address): void;
 /**
- * Validates that a grant has not expired (if expiry is set)
+ * Validates that a grant has not expired.
+ *
+ * @param grantFile - The grant file to check.
+ *   Must include expiry timestamp if time-limited.
+ * @param currentTime - Optional time override for testing.
+ *   Unix timestamp in seconds. Defaults to current time.
+ *
+ * @throws {GrantExpiredError} If grant has expired.
+ *   Request a new grant from the data owner.
+ *
+ * @example
+ * ```typescript
+ * validateGrantExpiry(grantFile);
+ * // Throws if current time > grantFile.expires
+ * ```
  *
- * @param grantFile - The grant file to check expiration for
- * @param currentTime - Optional override for current time (Unix timestamp)
+ * @category Permissions
  */
-declare function validateGrantExpiry(grantFile: GrantFile, currentTime?: number): void;
+export declare function validateGrantExpiry(grantFile: GrantFile, currentTime?: number): void;
 /**
- * Validates that a grant allows a specific operation
+ * Validates that a grant authorizes the requested operation.
+ *
+ * @param grantFile - The grant file to check.
+ *   Contains the authorized operation.
+ * @param requestedOperation - The operation to validate.
+ *   Must match the grant's operation exactly.
+ *
+ * @throws {OperationNotAllowedError} If operations don't match.
+ *   Request a grant for the specific operation needed.
+ *
+ * @example
+ * ```typescript
+ * validateOperationAccess(grantFile, 'llm_inference');
+ * // Throws if grantFile.operation !== 'llm_inference'
+ * ```
  *
- * @param grantFile - The grant file to validate operation access for
- * @param requestedOperation - The operation being requested to validate against the grant
+ * @category Permissions
  */
-declare function validateOperationAccess(grantFile: GrantFile, requestedOperation: string): void;
-
-export { GrantExpiredError, GrantSchemaError, GrantValidationError, type GrantValidationOptions, type GrantValidationResult, GranteeMismatchError, OperationNotAllowedError, validateGrant, validateGrantExpiry, validateGranteeAccess, validateOperationAccess };
+export declare function validateOperationAccess(grantFile: GrantFile, requestedOperation: string): void;

package/dist/utils/grantValidation.js

@@ -168,7 +168,7 @@ function validateGranteeAccess(grantFile, requestingAddress) {
 }
 function validateGrantExpiry(grantFile, currentTime) {
   if (grantFile.expires) {
-    const now = currentTime || Math.floor(Date.now() / 1e3);
+    const now = currentTime !== void 0 ? currentTime : Math.floor(Date.now() / 1e3);
     if (now > grantFile.expires) {
       throw new GrantExpiredError(
         "Permission denied: grant has expired",

package/dist/utils/grantValidation.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/grantValidation.ts"],"sourcesContent":["import { Address, getAddress } from \"viem\";\nimport Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport type { GrantFile } from \"../types/permissions\";\nimport grantFileSchema from \"../schemas/grantFile.schema.json\";\n\n/**\n * Base error class for grant validation failures\n *\n * @category Permissions\n */\nexport class GrantValidationError extends Error {\n  constructor(\n    message: string,\n    public details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.name = \"GrantValidationError\";\n  }\n}\n\n/**\n * Error thrown when a grant has expired\n *\n * @category Permissions\n */\nexport class GrantExpiredError extends GrantValidationError {\n  constructor(\n    message: string,\n    public expires: number,\n    public currentTime: number,\n  ) {\n    super(message, { expires, currentTime });\n    this.name = \"GrantExpiredError\";\n  }\n}\n\n/**\n * Error thrown when grantee doesn't match requesting address\n *\n * @category Permissions\n */\nexport class GranteeMismatchError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantee: Address,\n    public requestingAddress: Address,\n  ) {\n    super(message, { grantee, requestingAddress });\n    this.name = \"GranteeMismatchError\";\n  }\n}\n\n/**\n * Error thrown when operation is not allowed by grant\n *\n * @category Permissions\n */\nexport class OperationNotAllowedError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantedOperation: string,\n    public requestedOperation: string,\n  ) {\n    super(message, { grantedOperation, requestedOperation });\n    this.name = \"OperationNotAllowedError\";\n  }\n}\n\n/**\n * Error thrown when grant file structure is invalid\n *\n * @category Permissions\n */\nexport class GrantSchemaError extends GrantValidationError {\n  constructor(\n    message: string,\n    public schemaErrors: unknown[],\n    public invalidData: unknown,\n  ) {\n    super(message, { errors: schemaErrors, data: invalidData });\n    this.name = \"GrantSchemaError\";\n  }\n}\n\n/**\n * Ajv instance for grant file validation with draft 2020-12 support\n */\nconst ajv = new Ajv({\n  strict: true,\n  removeAdditional: false,\n  useDefaults: false,\n  coerceTypes: false,\n});\n\n// Add format validators (email, date, etc.)\naddFormats(ajv);\n\n/**\n * Compiled grant file schema validator\n */\nconst validateGrantFileSchema: ValidateFunction = ajv.compile(grantFileSchema);\n\n/**\n * Options for grant validation\n *\n * @category Permissions\n */\nexport interface GrantValidationOptions {\n  /** Enable JSON schema validation (default: true) */\n  schema?: boolean;\n  /** Grantee address to validate access for */\n  grantee?: Address;\n  /** Operation to validate permission for */\n  operation?: string;\n  /** Override current time for expiry checking (Unix timestamp) */\n  currentTime?: number;\n  /** Return detailed results instead of throwing (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Detailed validation result\n *\n * @category Permissions\n */\nexport interface GrantValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors encountered */\n  errors: Array<{\n    type: \"schema\" | \"business\";\n    field?: string;\n    message: string;\n    error?: Error;\n  }>;\n  /** The validated grant file (if validation passed) */\n  grant?: GrantFile;\n}\n\n/**\n * Validates a grant file with comprehensive schema and business rule checking.\n *\n * This function provides flexible validation with TypeScript overloads:\n * - When `throwOnError` is false (or `{ throwOnError: false }`), returns a detailed validation result\n * - When `throwOnError` is true (default), throws specific errors or returns the validated grant\n *\n * @param data - The grant file data to validate (unknown type for safety)\n * @param options - Validation options including grantee, operation, files, etc.\n * @returns Either a GrantFile (when throwing) or GrantValidationResult (when not throwing)\n * @throws {GrantSchemaError} When the grant file structure is invalid\n * @throws {GrantExpiredError} When the grant has expired\n * @throws {GranteeMismatchError} When the grantee doesn't match the requesting address\n * @throws {OperationNotAllowedError} When the requested operation is not allowed\n * @example\n * ```typescript\n * // Throwing mode (default) - returns GrantFile or throws\n * const grant = validateGrant(data, {\n *   grantee: '0x123...',\n *   operation: 'llm_inference',\n * });\n *\n * // Non-throwing mode - returns validation result\n * const result = validateGrant(data, {\n *   grantee: '0x123...',\n *   throwOnError: false\n * });\n * if (result.valid) {\n *   console.log('Grant is valid:', result.grant);\n * } else {\n *   console.log('Validation errors:', result.errors);\n * }\n * ```\n */\n\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions & { throwOnError: false },\n): GrantValidationResult;\n\nexport function validateGrant(\n  data: unknown,\n  options?:\n    | Omit<GrantValidationOptions, \"throwOnError\">\n    | (GrantValidationOptions & { throwOnError?: true }),\n): GrantFile;\n\n/**\n * Implementation function for grant validation with flexible return types\n *\n * @param data - The grant file data to validate\n * @param options - Validation configuration options\n * @returns Either a GrantFile or GrantValidationResult depending on throwOnError setting\n */\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions = {},\n): GrantFile | GrantValidationResult {\n  const {\n    schema = true,\n    grantee,\n    operation,\n    currentTime,\n    throwOnError = true,\n  } = options;\n\n  const errors: GrantValidationResult[\"errors\"] = [];\n  let grant: GrantFile | undefined;\n\n  // 1. Schema Validation\n  if (schema) {\n    try {\n      if (validateGrantFileSchema(data)) {\n        grant = data as GrantFile;\n      } else {\n        throw new GrantValidationError(\"Invalid grant file schema\");\n      }\n    } catch (error) {\n      if (error instanceof GrantValidationError) {\n        const schemaError = new GrantSchemaError(\n          error.message,\n          Array.isArray(error.details?.errors) ? error.details.errors : [],\n          data,\n        );\n        errors.push({\n          type: \"schema\",\n          message: error.message,\n          error: schemaError,\n        });\n      } else {\n        errors.push({\n          type: \"schema\",\n          message: `Schema validation failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  } else {\n    // Minimal type assertion if schema validation is skipped\n    grant = data as GrantFile;\n  }\n\n  // 2. Business Logic Validation (only if we have a valid grant)\n  if (grant) {\n    // Check grantee access\n    if (grantee) {\n      try {\n        validateGranteeAccess(grant, grantee);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n\n    // Check expiration\n    try {\n      validateGrantExpiry(grant, currentTime);\n    } catch (error) {\n      const field = extractFieldFromBusinessError(error);\n      errors.push({\n        type: \"business\",\n        field,\n        message:\n          error instanceof Error\n            ? error.message\n            : \"Unknown business rule error\",\n        error: error instanceof Error ? error : new Error(\"Unknown error\"),\n      });\n    }\n\n    // Check operation access\n    if (operation) {\n      try {\n        validateOperationAccess(grant, operation);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  }\n\n  // 3. Return Results\n  if (errors.length > 0) {\n    if (throwOnError) {\n      // Throw the most specific error we have\n      const firstError = errors[0];\n      if (firstError.error) {\n        throw firstError.error;\n      } else {\n        const combinedMessage = errors.map((e) => e.message).join(\"; \");\n        throw new GrantValidationError(\n          `Grant validation failed: ${combinedMessage}`,\n          { errors, data },\n        );\n      }\n    }\n\n    return { valid: false, errors, grant };\n  }\n\n  if (throwOnError) {\n    return grant as GrantFile;\n  } else {\n    return { valid: true, errors: [], grant: grant as GrantFile };\n  }\n}\n\n/**\n * Helper function to extract field name from business validation errors\n *\n * @param error - The validation error to extract field information from\n * @returns The field name associated with the error, or undefined if not applicable\n */\nfunction extractFieldFromBusinessError(error: unknown): string | undefined {\n  if (error instanceof GrantExpiredError) return \"expires\";\n  if (error instanceof GranteeMismatchError) return \"grantee\";\n  if (error instanceof OperationNotAllowedError) return \"operation\";\n  return undefined;\n}\n\n/**\n * Validates that a grant file allows access for a specific grantee\n *\n * @param grantFile - The grant file to validate access for\n * @param requestingAddress - The address requesting access to check against the grantee\n */\nexport function validateGranteeAccess(\n  grantFile: GrantFile,\n  requestingAddress: Address,\n): void {\n  const normalizedGrantee = getAddress(grantFile.grantee);\n  const normalizedRequesting = getAddress(requestingAddress);\n\n  if (normalizedGrantee !== normalizedRequesting) {\n    throw new GranteeMismatchError(\n      \"Permission denied: requesting address does not match grantee\",\n      grantFile.grantee,\n      requestingAddress,\n    );\n  }\n}\n\n/**\n * Validates that a grant has not expired (if expiry is set)\n *\n * @param grantFile - The grant file to check expiration for\n * @param currentTime - Optional override for current time (Unix timestamp)\n */\nexport function validateGrantExpiry(\n  grantFile: GrantFile,\n  currentTime?: number,\n): void {\n  if (grantFile.expires) {\n    const now = currentTime || Math.floor(Date.now() / 1000); // Current Unix timestamp\n\n    if (now > grantFile.expires) {\n      throw new GrantExpiredError(\n        \"Permission denied: grant has expired\",\n        grantFile.expires,\n        now,\n      );\n    }\n  }\n}\n\n/**\n * Validates that a grant allows a specific operation\n *\n * @param grantFile - The grant file to validate operation access for\n * @param requestedOperation - The operation being requested to validate against the grant\n */\nexport function validateOperationAccess(\n  grantFile: GrantFile,\n  requestedOperation: string,\n): void {\n  if (grantFile.operation !== requestedOperation) {\n    throw new OperationNotAllowedError(\n      \"Permission denied: operation not allowed by grant\",\n      grantFile.operation,\n      requestedOperation,\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/grantValidation.ts"],"sourcesContent":["/**\n * Provides comprehensive validation for permission grant files.\n *\n * @remarks\n * This module implements multi-layer validation for grant files including\n * JSON schema validation, business rule checking, expiration verification,\n * and access control validation. It provides both throwing and non-throwing\n * modes for flexible error handling.\n *\n * @category Permissions\n * @module utils/grantValidation\n */\n\nimport type { Address } from \"viem\";\nimport { getAddress } from \"viem\";\nimport Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport type { GrantFile } from \"../types/permissions\";\nimport grantFileSchema from \"../schemas/grantFile.schema.json\";\n\n/**\n * Indicates a general grant validation failure.\n *\n * @remarks\n * Base class for all grant validation errors. Provides structured\n * error details for debugging and recovery.\n *\n * @category Permissions\n */\nexport class GrantValidationError extends Error {\n  constructor(\n    message: string,\n    public details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.name = \"GrantValidationError\";\n  }\n}\n\n/**\n * Indicates that a grant has expired and is no longer valid.\n *\n * @remarks\n * Thrown when attempting to use a grant past its expiration timestamp.\n * Includes both the expiration time and current time for debugging.\n *\n * @category Permissions\n */\nexport class GrantExpiredError extends GrantValidationError {\n  constructor(\n    message: string,\n    public expires: number,\n    public currentTime: number,\n  ) {\n    super(message, { expires, currentTime });\n    this.name = \"GrantExpiredError\";\n  }\n}\n\n/**\n * Indicates that the requesting address doesn't match the grant's grantee.\n *\n * @remarks\n * Thrown when a user attempts to use a grant that was issued to a\n * different address. This prevents unauthorized use of permissions.\n *\n * @category Permissions\n */\nexport class GranteeMismatchError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantee: Address,\n    public requestingAddress: Address,\n  ) {\n    super(message, { grantee, requestingAddress });\n    this.name = \"GranteeMismatchError\";\n  }\n}\n\n/**\n * Indicates that the requested operation is not allowed by the grant.\n *\n * @remarks\n * Thrown when attempting an operation that differs from what the\n * grant authorizes. Includes both granted and requested operations.\n *\n * @category Permissions\n */\nexport class OperationNotAllowedError extends GrantValidationError {\n  constructor(\n    message: string,\n    public grantedOperation: string,\n    public requestedOperation: string,\n  ) {\n    super(message, { grantedOperation, requestedOperation });\n    this.name = \"OperationNotAllowedError\";\n  }\n}\n\n/**\n * Indicates that the grant file structure violates the JSON schema.\n *\n * @remarks\n * Thrown when a grant file doesn't conform to the expected schema.\n * Includes detailed schema validation errors and the invalid data.\n *\n * @category Permissions\n */\nexport class GrantSchemaError extends GrantValidationError {\n  constructor(\n    message: string,\n    public schemaErrors: unknown[],\n    public invalidData: unknown,\n  ) {\n    super(message, { errors: schemaErrors, data: invalidData });\n    this.name = \"GrantSchemaError\";\n  }\n}\n\n/**\n * Ajv instance configured for strict grant file validation.\n *\n * @internal\n */\nconst ajv = new Ajv({\n  strict: true,\n  removeAdditional: false,\n  useDefaults: false,\n  coerceTypes: false,\n});\n\n// Add format validators (email, date, etc.)\naddFormats(ajv);\n\n/**\n * Pre-compiled grant file schema validator for performance.\n *\n * @internal\n */\nconst validateGrantFileSchema: ValidateFunction = ajv.compile(grantFileSchema);\n\n/**\n * Configures grant validation behavior and scope.\n *\n * @remarks\n * Controls which validations to perform and how to handle errors.\n * Allows selective validation of specific aspects of a grant.\n *\n * @category Permissions\n */\nexport interface GrantValidationOptions {\n  /** Enable JSON schema validation (default: true) */\n  schema?: boolean;\n  /** Grantee address to validate access for */\n  grantee?: Address;\n  /** Operation to validate permission for */\n  operation?: string;\n  /** Override current time for expiry checking (Unix timestamp) */\n  currentTime?: number;\n  /** Return detailed results instead of throwing (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Represents the detailed result of grant validation.\n *\n * @remarks\n * Provides comprehensive validation results including all errors\n * encountered during validation. Used in non-throwing mode.\n *\n * @category Permissions\n */\nexport interface GrantValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors encountered */\n  errors: Array<{\n    type: \"schema\" | \"business\";\n    field?: string;\n    message: string;\n    error?: Error;\n  }>;\n  /** The validated grant file (if validation passed) */\n  grant?: GrantFile;\n}\n\n/**\n * Validates a grant file with comprehensive schema and business rule checking.\n *\n * This function provides flexible validation with TypeScript overloads:\n * - When `throwOnError` is false (or `{ throwOnError: false }`), returns a detailed validation result\n * - When `throwOnError` is true (default), throws specific errors or returns the validated grant\n *\n * @param data - The grant file data to validate (unknown type for safety)\n * @param options - Validation options including grantee, operation, files, etc.\n * @returns Either a GrantFile (when throwing) or GrantValidationResult (when not throwing)\n * @throws {GrantSchemaError} When the grant file structure is invalid\n * @throws {GrantExpiredError} When the grant has expired\n * @throws {GranteeMismatchError} When the grantee doesn't match the requesting address\n * @throws {OperationNotAllowedError} When the requested operation is not allowed\n * @example\n * ```typescript\n * // Throwing mode (default) - returns GrantFile or throws\n * const grant = validateGrant(data, {\n *   grantee: '0x123...',\n *   operation: 'llm_inference',\n * });\n *\n * // Non-throwing mode - returns validation result\n * const result = validateGrant(data, {\n *   grantee: '0x123...',\n *   throwOnError: false\n * });\n * if (result.valid) {\n *   console.log('Grant is valid:', result.grant);\n * } else {\n *   console.log('Validation errors:', result.errors);\n * }\n * ```\n */\n\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions & { throwOnError: false },\n): GrantValidationResult;\n\nexport function validateGrant(\n  data: unknown,\n  options?:\n    | Omit<GrantValidationOptions, \"throwOnError\">\n    | (GrantValidationOptions & { throwOnError?: true }),\n): GrantFile;\n\n/** @internal */\nexport function validateGrant(\n  data: unknown,\n  options: GrantValidationOptions = {},\n): GrantFile | GrantValidationResult {\n  const {\n    schema = true,\n    grantee,\n    operation,\n    currentTime,\n    throwOnError = true,\n  } = options;\n\n  const errors: GrantValidationResult[\"errors\"] = [];\n  let grant: GrantFile | undefined;\n\n  // 1. Schema Validation\n  if (schema) {\n    try {\n      if (validateGrantFileSchema(data)) {\n        grant = data as GrantFile;\n      } else {\n        throw new GrantValidationError(\"Invalid grant file schema\");\n      }\n    } catch (error) {\n      if (error instanceof GrantValidationError) {\n        const schemaError = new GrantSchemaError(\n          error.message,\n          Array.isArray(error.details?.errors) ? error.details.errors : [],\n          data,\n        );\n        errors.push({\n          type: \"schema\",\n          message: error.message,\n          error: schemaError,\n        });\n      } else {\n        errors.push({\n          type: \"schema\",\n          message: `Schema validation failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  } else {\n    // Minimal type assertion if schema validation is skipped\n    grant = data as GrantFile;\n  }\n\n  // 2. Business Logic Validation (only if we have a valid grant)\n  if (grant) {\n    // Check grantee access\n    if (grantee) {\n      try {\n        validateGranteeAccess(grant, grantee);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n\n    // Check expiration\n    try {\n      validateGrantExpiry(grant, currentTime);\n    } catch (error) {\n      const field = extractFieldFromBusinessError(error);\n      errors.push({\n        type: \"business\",\n        field,\n        message:\n          error instanceof Error\n            ? error.message\n            : \"Unknown business rule error\",\n        error: error instanceof Error ? error : new Error(\"Unknown error\"),\n      });\n    }\n\n    // Check operation access\n    if (operation) {\n      try {\n        validateOperationAccess(grant, operation);\n      } catch (error) {\n        const field = extractFieldFromBusinessError(error);\n        errors.push({\n          type: \"business\",\n          field,\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Unknown business rule error\",\n          error: error instanceof Error ? error : new Error(\"Unknown error\"),\n        });\n      }\n    }\n  }\n\n  // 3. Return Results\n  if (errors.length > 0) {\n    if (throwOnError) {\n      // Throw the most specific error we have\n      const firstError = errors[0];\n      if (firstError.error) {\n        throw firstError.error;\n      } else {\n        const combinedMessage = errors.map((e) => e.message).join(\"; \");\n        throw new GrantValidationError(\n          `Grant validation failed: ${combinedMessage}`,\n          { errors, data },\n        );\n      }\n    }\n\n    return { valid: false, errors, grant };\n  }\n\n  if (throwOnError) {\n    return grant as GrantFile;\n  } else {\n    return { valid: true, errors: [], grant: grant as GrantFile };\n  }\n}\n\n/**\n * Extracts the field name from business validation errors for reporting.\n *\n * @param error - The validation error to analyze\n * @returns The field name associated with the error, or undefined\n *\n * @internal\n */\nfunction extractFieldFromBusinessError(error: unknown): string | undefined {\n  if (error instanceof GrantExpiredError) return \"expires\";\n  if (error instanceof GranteeMismatchError) return \"grantee\";\n  if (error instanceof OperationNotAllowedError) return \"operation\";\n  return undefined;\n}\n\n/**\n * Validates that a grant allows access for the requesting address.\n *\n * @param grantFile - The grant file to validate.\n *   Obtain from permission operations or server responses.\n * @param requestingAddress - The address requesting access.\n *   Typically the current wallet address.\n *\n * @throws {GranteeMismatchError} If addresses don't match.\n *   Ensure using the correct wallet that received the grant.\n *\n * @example\n * ```typescript\n * validateGranteeAccess(grantFile, walletAddress);\n * // Throws if walletAddress doesn't match grantFile.grantee\n * ```\n *\n * @category Permissions\n */\nexport function validateGranteeAccess(\n  grantFile: GrantFile,\n  requestingAddress: Address,\n): void {\n  const normalizedGrantee = getAddress(grantFile.grantee);\n  const normalizedRequesting = getAddress(requestingAddress);\n\n  if (normalizedGrantee !== normalizedRequesting) {\n    throw new GranteeMismatchError(\n      \"Permission denied: requesting address does not match grantee\",\n      grantFile.grantee,\n      requestingAddress,\n    );\n  }\n}\n\n/**\n * Validates that a grant has not expired.\n *\n * @param grantFile - The grant file to check.\n *   Must include expiry timestamp if time-limited.\n * @param currentTime - Optional time override for testing.\n *   Unix timestamp in seconds. Defaults to current time.\n *\n * @throws {GrantExpiredError} If grant has expired.\n *   Request a new grant from the data owner.\n *\n * @example\n * ```typescript\n * validateGrantExpiry(grantFile);\n * // Throws if current time > grantFile.expires\n * ```\n *\n * @category Permissions\n */\nexport function validateGrantExpiry(\n  grantFile: GrantFile,\n  currentTime?: number,\n): void {\n  if (grantFile.expires) {\n    const now =\n      currentTime !== undefined ? currentTime : Math.floor(Date.now() / 1000); // Current Unix timestamp\n\n    if (now > grantFile.expires) {\n      throw new GrantExpiredError(\n        \"Permission denied: grant has expired\",\n        grantFile.expires,\n        now,\n      );\n    }\n  }\n}\n\n/**\n * Validates that a grant authorizes the requested operation.\n *\n * @param grantFile - The grant file to check.\n *   Contains the authorized operation.\n * @param requestedOperation - The operation to validate.\n *   Must match the grant's operation exactly.\n *\n * @throws {OperationNotAllowedError} If operations don't match.\n *   Request a grant for the specific operation needed.\n *\n * @example\n * ```typescript\n * validateOperationAccess(grantFile, 'llm_inference');\n * // Throws if grantFile.operation !== 'llm_inference'\n * ```\n *\n * @category Permissions\n */\nexport function validateOperationAccess(\n  grantFile: GrantFile,\n  requestedOperation: string,\n): void {\n  if (grantFile.operation !== requestedOperation) {\n    throw new OperationNotAllowedError(\n      \"Permission denied: operation not allowed by grant\",\n      grantFile.operation,\n      requestedOperation,\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/utils/grants.cjs

@@ -54,7 +54,7 @@ async function retrieveAndValidateGrant(grantUrl, relayerUrl) {
   const grantFile = await (0, import_grantFiles.retrieveGrantFile)(grantUrl, relayerUrl);
   return grantFile;
 }
-async function checkGrantAccess(grantUrl, requestingAddress, operation, fileIds, relayerUrl) {
+async function checkGrantAccess(grantUrl, requestingAddress, operation, _fileIds, relayerUrl) {
   try {
     const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);
     (0, import_grantValidation.validateGrant)(grantFile, {

package/dist/utils/grants.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["import { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * High-level utilities for working with grants in the Vana SDK\n */\n\n/**\n * Creates and validates a grant file from permission parameters\n *\n * @param params - The permission parameters to create and validate the grant from\n * @returns The validated grant file object\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS\n *\n * @param params - The permission parameters to create the grant from\n * @param relayerUrl - The URL of the relayer service for IPFS storage\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to the validated grant file\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,wBAIO;AACP,6BAAoD;AAY7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,gBAAY,mCAAgB,MAAM;AAGxC,MAAI;AACF,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AASA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,UAAM,kCAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AASA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,UAAM,qCAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,SACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,6CAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}
+{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["/**\n * Provides high-level grant management utilities for the Vana permission system.\n *\n * @remarks\n * This module simplifies grant file creation, validation, storage, and retrieval.\n * Grants are the core mechanism for permission management in Vana, allowing users\n * to delegate specific operations to applications and services.\n *\n * @category Permissions\n * @module grants\n */\n\nimport type { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * Creates and validates a grant file from permission parameters.\n *\n * @remarks\n * Combines grant creation with immediate validation to ensure only valid\n * grants are created. Validates schema compliance, grantee address, and\n * operation parameters before returning the grant file.\n *\n * @param params - The permission parameters to create and validate the grant from.\n *   Obtain from user input or application configuration.\n * @returns The validated grant file object ready for storage\n *\n * @throws {GrantValidationError} When grant parameters are invalid.\n *   Check error message for specific validation failures.\n *\n * @example\n * ```typescript\n * const grant = createValidatedGrant({\n *   grantee: '0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb',\n *   operation: 'llm_inference',\n *   parameters: { model: 'gpt-4', maxTokens: 1000 },\n *   expiresAt: Date.now() + 86400000 // 24 hours\n * });\n * ```\n *\n * @category Permissions\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS.\n *\n * @remarks\n * Combines grant creation, validation, and IPFS storage in a single operation.\n * The grant is stored immutably on IPFS and can be referenced by its URL in\n * on-chain permission records.\n *\n * @param params - The permission parameters to create the grant from.\n *   Obtain from user input or application configuration.\n * @param relayerUrl - The URL of the relayer service for IPFS storage.\n *   Obtain from SDK configuration or environment.\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n *\n * @throws {GrantValidationError} When grant parameters are invalid.\n *   Check error message for specific validation failures.\n * @throws {Error} When IPFS storage fails.\n *   Retry with exponential backoff or check relayer status.\n *\n * @example\n * ```typescript\n * const { grantFile, grantUrl } = await createAndStoreGrant(\n *   {\n *     grantee: applicationAddress,\n *     operation: 'data_processing',\n *     parameters: { dataTypes: ['medical', 'financial'] }\n *   },\n *   'https://relayer.vana.org'\n * );\n *\n * console.log('Grant stored at:', grantUrl);\n * ```\n *\n * @category Permissions\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS.\n *\n * @remarks\n * Fetches a grant file from IPFS and performs basic validation to ensure\n * the retrieved data is a valid grant structure. Use this when you need to\n * verify or process existing grants.\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve.\n *   Obtain from on-chain permission records or grant events.\n * @param relayerUrl - Optional URL of the relayer service.\n *   If not provided, uses default IPFS gateways.\n * @returns Promise resolving to the validated grant file\n *\n * @throws {Error} When grant retrieval fails.\n *   Check network connectivity or IPFS gateway availability.\n * @throws {Error} When grant file is malformed.\n *   Verify the grant URL points to a valid grant file.\n *\n * @example\n * ```typescript\n * const grant = await retrieveAndValidateGrant(\n *   'ipfs://QmXxx...'\n * );\n *\n * console.log('Grant for:', grant.grantee);\n * console.log('Operation:', grant.operation);\n * ```\n *\n * @category Permissions\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  _fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,wBAIO;AACP,6BAAoD;AA6B7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,gBAAY,mCAAgB,MAAM;AAGxC,MAAI;AACF,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AAqCA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,UAAM,kCAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AAiCA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,UAAM,qCAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,UACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,6CAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}

package/dist/utils/grants.d.ts

@@ -1,46 +1,126 @@
-import { Address } from 'viem';
-import { GrantPermissionParams, GrantFile } from '../types/permissions.js';
-
 /**
- * High-level utilities for working with grants in the Vana SDK
+ * Provides high-level grant management utilities for the Vana permission system.
+ *
+ * @remarks
+ * This module simplifies grant file creation, validation, storage, and retrieval.
+ * Grants are the core mechanism for permission management in Vana, allowing users
+ * to delegate specific operations to applications and services.
+ *
+ * @category Permissions
+ * @module grants
  */
+import type { Address } from "viem";
+import type { GrantFile, GrantPermissionParams } from "../types/permissions";
 /**
- * Creates and validates a grant file from permission parameters
+ * Creates and validates a grant file from permission parameters.
+ *
+ * @remarks
+ * Combines grant creation with immediate validation to ensure only valid
+ * grants are created. Validates schema compliance, grantee address, and
+ * operation parameters before returning the grant file.
+ *
+ * @param params - The permission parameters to create and validate the grant from.
+ *   Obtain from user input or application configuration.
+ * @returns The validated grant file object ready for storage
+ *
+ * @throws {GrantValidationError} When grant parameters are invalid.
+ *   Check error message for specific validation failures.
  *
- * @param params - The permission parameters to create and validate the grant from
- * @returns The validated grant file object
+ * @example
+ * ```typescript
+ * const grant = createValidatedGrant({
+ *   grantee: '0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb',
+ *   operation: 'llm_inference',
+ *   parameters: { model: 'gpt-4', maxTokens: 1000 },
+ *   expiresAt: Date.now() + 86400000 // 24 hours
+ * });
+ * ```
+ *
+ * @category Permissions
  */
-declare function createValidatedGrant(params: GrantPermissionParams): GrantFile;
+export declare function createValidatedGrant(params: GrantPermissionParams): GrantFile;
 /**
- * Creates a grant file and stores it in IPFS
+ * Creates a grant file and stores it in IPFS.
+ *
+ * @remarks
+ * Combines grant creation, validation, and IPFS storage in a single operation.
+ * The grant is stored immutably on IPFS and can be referenced by its URL in
+ * on-chain permission records.
  *
- * @param params - The permission parameters to create the grant from
- * @param relayerUrl - The URL of the relayer service for IPFS storage
+ * @param params - The permission parameters to create the grant from.
+ *   Obtain from user input or application configuration.
+ * @param relayerUrl - The URL of the relayer service for IPFS storage.
+ *   Obtain from SDK configuration or environment.
  * @returns Promise resolving to an object containing the grant file and its IPFS URL
+ *
+ * @throws {GrantValidationError} When grant parameters are invalid.
+ *   Check error message for specific validation failures.
+ * @throws {Error} When IPFS storage fails.
+ *   Retry with exponential backoff or check relayer status.
+ *
+ * @example
+ * ```typescript
+ * const { grantFile, grantUrl } = await createAndStoreGrant(
+ *   {
+ *     grantee: applicationAddress,
+ *     operation: 'data_processing',
+ *     parameters: { dataTypes: ['medical', 'financial'] }
+ *   },
+ *   'https://relayer.vana.org'
+ * );
+ *
+ * console.log('Grant stored at:', grantUrl);
+ * ```
+ *
+ * @category Permissions
  */
-declare function createAndStoreGrant(params: GrantPermissionParams, relayerUrl: string): Promise<{
+export declare function createAndStoreGrant(params: GrantPermissionParams, relayerUrl: string): Promise<{
     grantFile: GrantFile;
     grantUrl: string;
 }>;
 /**
- * Retrieves and validates a grant file from IPFS
+ * Retrieves and validates a grant file from IPFS.
  *
- * @param grantUrl - The IPFS URL of the grant file to retrieve
- * @param relayerUrl - Optional URL of the relayer service
+ * @remarks
+ * Fetches a grant file from IPFS and performs basic validation to ensure
+ * the retrieved data is a valid grant structure. Use this when you need to
+ * verify or process existing grants.
+ *
+ * @param grantUrl - The IPFS URL of the grant file to retrieve.
+ *   Obtain from on-chain permission records or grant events.
+ * @param relayerUrl - Optional URL of the relayer service.
+ *   If not provided, uses default IPFS gateways.
  * @returns Promise resolving to the validated grant file
+ *
+ * @throws {Error} When grant retrieval fails.
+ *   Check network connectivity or IPFS gateway availability.
+ * @throws {Error} When grant file is malformed.
+ *   Verify the grant URL points to a valid grant file.
+ *
+ * @example
+ * ```typescript
+ * const grant = await retrieveAndValidateGrant(
+ *   'ipfs://QmXxx...'
+ * );
+ *
+ * console.log('Grant for:', grant.grantee);
+ * console.log('Operation:', grant.operation);
+ * ```
+ *
+ * @category Permissions
  */
-declare function retrieveAndValidateGrant(grantUrl: string, relayerUrl?: string): Promise<GrantFile>;
+export declare function retrieveAndValidateGrant(grantUrl: string, relayerUrl?: string): Promise<GrantFile>;
 /**
  * Checks if a grant allows access for a specific request
  *
  * @param grantUrl - The IPFS URL of the grant file to check
  * @param requestingAddress - The address making the access request
  * @param operation - The operation being requested
- * @param fileIds - Array of file IDs being accessed (currently unused but part of interface)
+ * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)
  * @param relayerUrl - Optional URL of the relayer service
  * @returns Promise resolving to access result with allowed status, reason, and grant file
  */
-declare function checkGrantAccess(grantUrl: string, requestingAddress: Address, operation: string, fileIds: number[], relayerUrl?: string): Promise<{
+export declare function checkGrantAccess(grantUrl: string, requestingAddress: Address, operation: string, _fileIds: number[], relayerUrl?: string): Promise<{
     allowed: boolean;
     reason?: string;
     grantFile?: GrantFile;
@@ -51,20 +131,18 @@ declare function checkGrantAccess(grantUrl: string, requestingAddress: Address,
  * @param grantFile - The grant file to check for expiration
  * @returns True if the grant has expired, false otherwise
  */
-declare function isGrantExpired(grantFile: GrantFile): boolean;
+export declare function isGrantExpired(grantFile: GrantFile): boolean;
 /**
  * Utility to get the time remaining before grant expires (in seconds)
  *
  * @param grantFile - The grant file to check time remaining for
  * @returns Number of seconds remaining, or null if no expiration is set
  */
-declare function getGrantTimeRemaining(grantFile: GrantFile): number | null;
+export declare function getGrantTimeRemaining(grantFile: GrantFile): number | null;
 /**
  * Creates a human-readable summary of a grant
  *
  * @param grantFile - The grant file to create a summary for
  * @returns A human-readable string describing the grant
  */
-declare function summarizeGrant(grantFile: GrantFile): string;
-
-export { checkGrantAccess, createAndStoreGrant, createValidatedGrant, getGrantTimeRemaining, isGrantExpired, retrieveAndValidateGrant, summarizeGrant };
+export declare function summarizeGrant(grantFile: GrantFile): string;

package/dist/utils/grants.js

@@ -29,7 +29,7 @@ async function retrieveAndValidateGrant(grantUrl, relayerUrl) {
   const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);
   return grantFile;
 }
-async function checkGrantAccess(grantUrl, requestingAddress, operation, fileIds, relayerUrl) {
+async function checkGrantAccess(grantUrl, requestingAddress, operation, _fileIds, relayerUrl) {
   try {
     const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);
     validateGrant(grantFile, {