feat(core): Add pluggable auth providers, storage hooks, multi-upstream cache awareness, and PyPI/RubyGems protocol implementations

ts/core/interfaces.auth.ts

@@ -0,0 +1,91 @@
+import type { IAuthToken, ICredentials, TRegistryProtocol } from './interfaces.core.js';
+
+/**
+ * Options for creating a token
+ */
+export interface ITokenOptions {
+  /** Whether the token is readonly */
+  readonly?: boolean;
+  /** Permission scopes */
+  scopes?: string[];
+  /** Expiration time in seconds */
+  expiresIn?: number;
+}
+
+/**
+ * Pluggable authentication provider interface.
+ * Implement this to integrate external auth systems (LDAP, OAuth, SSO, OIDC).
+ *
+ * @example
+ * ```typescript
+ * class LdapAuthProvider implements IAuthProvider {
+ *   constructor(private ldap: LdapClient, private redis: RedisClient) {}
+ *
+ *   async authenticate(credentials: ICredentials): Promise<string | null> {
+ *     return await this.ldap.bind(credentials.username, credentials.password);
+ *   }
+ *
+ *   async validateToken(token: string): Promise<IAuthToken | null> {
+ *     return await this.redis.get(`token:${token}`);
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface IAuthProvider {
+  /**
+   * Initialize the auth provider (optional)
+   */
+  init?(): Promise<void>;
+
+  /**
+   * Authenticate user credentials (login flow)
+   * @param credentials - Username and password
+   * @returns User ID on success, null on failure
+   */
+  authenticate(credentials: ICredentials): Promise<string | null>;
+
+  /**
+   * Validate an existing token
+   * @param token - Token string (UUID or JWT)
+   * @param protocol - Optional protocol hint for optimization
+   * @returns Auth token info or null if invalid
+   */
+  validateToken(token: string, protocol?: TRegistryProtocol): Promise<IAuthToken | null>;
+
+  /**
+   * Create a new token for a user
+   * @param userId - User ID
+   * @param protocol - Protocol type (npm, oci, maven, etc.)
+   * @param options - Token options (readonly, scopes, expiration)
+   * @returns Token string
+   */
+  createToken(userId: string, protocol: TRegistryProtocol, options?: ITokenOptions): Promise<string>;
+
+  /**
+   * Revoke a token
+   * @param token - Token string to revoke
+   */
+  revokeToken(token: string): Promise<void>;
+
+  /**
+   * Check if user has permission for an action
+   * @param token - Auth token (or null for anonymous)
+   * @param resource - Resource being accessed (e.g., "npm:package:lodash")
+   * @param action - Action being performed (read, write, push, pull, delete)
+   * @returns true if authorized
+   */
+  authorize(token: IAuthToken | null, resource: string, action: string): Promise<boolean>;
+
+  /**
+   * List all tokens for a user (optional)
+   * @param userId - User ID
+   * @returns List of token info
+   */
+  listUserTokens?(userId: string): Promise<Array<{
+    key: string;
+    readonly: boolean;
+    created: string;
+    protocol?: TRegistryProtocol;
+  }>>;
+}