smartregistry/ts/interfaces.ts

/**
 * Interfaces and types for OCI Distribution Specification compliant registry
 */

/**
 * Credentials for authentication
 */
export interface IRegistryCredentials {
  username: string;
  password: string;
}

/**
 * Actions that can be performed on a repository
 */
export type TRegistryAction = 'pull' | 'push' | 'delete' | '*';

/**
 * JWT token structure for OCI registry authentication
 */
export interface IRegistryToken {
  /** Issuer */
  iss: string;
  /** Subject (user identifier) */
  sub: string;
  /** Audience (service name) */
  aud: string;
  /** Expiration timestamp */
  exp: number;
  /** Not before timestamp */
  nbf: number;
  /** Issued at timestamp */
  iat: number;
  /** JWT ID */
  jti?: string;
  /** Access permissions */
  access: Array<{
    type: 'repository' | 'registry';
    name: string;
    actions: TRegistryAction[];
  }>;
}

/**
 * Callback function for user login - returns JWT token
 * @param credentials - User credentials
 * @returns JWT token string
 */
export type TLoginCallback = (
  credentials: IRegistryCredentials
) => Promise<string>;

/**
 * Callback function for authorization check
 * @param token - JWT token string
 * @param repository - Repository name (e.g., "library/nginx")
 * @param action - Action to perform
 * @returns true if authorized, false otherwise
 */
export type TAuthCallback = (
  token: string,
  repository: string,
  action: TRegistryAction
) => Promise<boolean>;

/**
 * Configuration for the registry
 */
export interface IRegistryConfig {
  /** Storage bucket configuration */
  storage: {
    accessKey: string;
    accessSecret: string;
    endpoint: string;
    port?: number;
    useSsl?: boolean;
    region?: string;
    bucketName: string;
  };
  /** Service name for token authentication */
  serviceName: string;
  /** Token realm (authorization server URL) */
  tokenRealm: string;
  /** Login callback */
  loginCallback: TLoginCallback;
  /** Authorization callback */
  authCallback: TAuthCallback;
}

/**
 * OCI manifest structure
 */
export interface IOciManifest {
  schemaVersion: number;
  mediaType: string;
  config: {
    mediaType: string;
    size: number;
    digest: string;
  };
  layers: Array<{
    mediaType: string;
    size: number;
    digest: string;
    urls?: string[];
  }>;
  subject?: {
    mediaType: string;
    size: number;
    digest: string;
  };
  annotations?: { [key: string]: string };
}

/**
 * OCI Image Index (manifest list)
 */
export interface IOciImageIndex {
  schemaVersion: number;
  mediaType: string;
  manifests: Array<{
    mediaType: string;
    size: number;
    digest: string;
    platform?: {
      architecture: string;
      os: string;
      'os.version'?: string;
      'os.features'?: string[];
      variant?: string;
      features?: string[];
    };
    annotations?: { [key: string]: string };
  }>;
  subject?: {
    mediaType: string;
    size: number;
    digest: string;
  };
  annotations?: { [key: string]: string };
}

/**
 * Upload session for chunked blob uploads
 */
export interface IUploadSession {
  uploadId: string;
  repository: string;
  chunks: Buffer[];
  totalSize: number;
  createdAt: Date;
  lastActivity: Date;
}

/**
 * Tag list response
 */
export interface ITagList {
  name: string;
  tags: string[];
}

/**
 * Referrers response
 */
export interface IReferrersResponse {
  schemaVersion: number;
  mediaType: string;
  manifests: Array<{
    mediaType: string;
    size: number;
    digest: string;
    artifactType?: string;
    annotations?: { [key: string]: string };
  }>;
}

/**
 * Registry error response
 */
export interface IRegistryError {
  errors: Array<{
    code: string;
    message: string;
    detail?: any;
  }>;
}

/**
 * Pagination options for listing
 */
export interface IPaginationOptions {
  /** Maximum number of results to return */
  n?: number;
  /** Last entry from previous request */
  last?: string;
}