smartregistry/ts/core/interfaces.core.ts

/**
 * Core interfaces for the composable registry system
 */

import type * as plugins from '../plugins.js';

/**
 * Registry protocol types
 */
export type TRegistryProtocol = 'oci' | 'npm' | 'maven' | 'cargo' | 'composer' | 'pypi' | 'rubygems';

/**
 * Unified action types across protocols
 */
export type TRegistryAction = 'pull' | 'push' | 'delete' | 'read' | 'write' | '*';

/**
 * Unified authentication token
 */
export interface IAuthToken {
  /** Token type/protocol */
  type: TRegistryProtocol;
  /** User ID */
  userId: string;
  /** Permission scopes (e.g., "npm:package:foo:write", "oci:repository:bar:push") */
  scopes: string[];
  /** Token expiration */
  expiresAt?: Date;
  /** Read-only flag */
  readonly?: boolean;
  /** Additional metadata */
  metadata?: Record<string, any>;
}

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

/**
 * Storage backend configuration
 * Extends IS3Descriptor from @tsclass/tsclass with bucketName
 */
export interface IStorageConfig extends plugins.tsclass.storage.IS3Descriptor {
  bucketName: string;
}

/**
 * Authentication configuration
 */
export interface IAuthConfig {
  /** JWT secret for OCI tokens */
  jwtSecret: string;
  /** Token storage type */
  tokenStore: 'memory' | 'redis' | 'database';
  /** NPM token settings */
  npmTokens: {
    enabled: boolean;
    defaultReadonly?: boolean;
  };
  /** OCI token settings */
  ociTokens: {
    enabled: boolean;
    realm: string;
    service: string;
  };
  /** PyPI token settings */
  pypiTokens?: {
    enabled: boolean;
    defaultReadonly?: boolean;
  };
  /** RubyGems token settings */
  rubygemsTokens?: {
    enabled: boolean;
    defaultReadonly?: boolean;
  };
}

/**
 * Protocol-specific configuration
 */
export interface IProtocolConfig {
  enabled: boolean;
  basePath: string;
  features?: Record<string, boolean>;
}

/**
 * Main registry configuration
 */
export interface IRegistryConfig {
  storage: IStorageConfig;
  auth: IAuthConfig;
  oci?: IProtocolConfig;
  npm?: IProtocolConfig;
  maven?: IProtocolConfig;
  cargo?: IProtocolConfig;
  composer?: IProtocolConfig;
  pypi?: IProtocolConfig;
  rubygems?: IProtocolConfig;
}

/**
 * Storage backend interface
 */
export interface IStorageBackend {
  /**
   * Get an object from storage
   */
  getObject(key: string): Promise<Buffer | null>;

  /**
   * Store an object
   */
  putObject(key: string, data: Buffer, metadata?: Record<string, string>): Promise<void>;

  /**
   * Delete an object
   */
  deleteObject(key: string): Promise<void>;

  /**
   * List objects with a prefix
   */
  listObjects(prefix: string): Promise<string[]>;

  /**
   * Check if an object exists
   */
  objectExists(key: string): Promise<boolean>;

  /**
   * Get object metadata
   */
  getMetadata(key: string): Promise<Record<string, string> | null>;
}

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

/**
 * Base request context
 */
export interface IRequestContext {
  method: string;
  path: string;
  headers: Record<string, string>;
  query: Record<string, string>;
  body?: any;
  /**
   * Raw request body as bytes. MUST be provided for content-addressable operations
   * (OCI manifests, blobs) to ensure digest calculation matches client expectations.
   * If not provided, falls back to 'body' field.
   */
  rawBody?: Buffer;
  token?: string;
}

/**
 * Base response structure
 */
export interface IResponse {
  status: number;
  headers: Record<string, string>;
  body?: any;
}