@push.rocks/smartregistry 2.3.0 → 2.4.0

package/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;
+  }>>;
+}

package/ts/core/interfaces.core.ts

@@ -4,6 +4,8 @@
 
 import type * as plugins from '../plugins.js';
 import type { IProtocolUpstreamConfig } from '../upstream/interfaces.upstream.js';
+import type { IAuthProvider } from './interfaces.auth.js';
+import type { IStorageHooks } from './interfaces.storage.js';
 
 /**
  * Registry protocol types
@@ -97,6 +99,20 @@ export interface IProtocolConfig {
 export interface IRegistryConfig {
   storage: IStorageConfig;
   auth: IAuthConfig;
+
+  /**
+   * Custom authentication provider.
+   * If not provided, uses the default in-memory auth provider.
+   * Implement IAuthProvider to integrate LDAP, OAuth, SSO, etc.
+   */
+  authProvider?: IAuthProvider;
+
+  /**
+   * Storage event hooks for quota tracking, audit logging, etc.
+   * Called before/after storage operations.
+   */
+  storageHooks?: IStorageHooks;
+
   oci?: IProtocolConfig;
   npm?: IProtocolConfig;
   maven?: IProtocolConfig;
@@ -152,6 +168,24 @@ export interface IRegistryError {
   }>;
 }
 
+/**
+ * Actor information - identifies who is performing the request
+ */
+export interface IRequestActor {
+  /** User ID (from validated token) */
+  userId?: string;
+  /** Token ID/hash for audit purposes */
+  tokenId?: string;
+  /** Client IP address */
+  ip?: string;
+  /** Client User-Agent */
+  userAgent?: string;
+  /** Organization ID (for multi-tenant setups) */
+  orgId?: string;
+  /** Session ID */
+  sessionId?: string;
+}
+
 /**
  * Base request context
  */
@@ -168,6 +202,11 @@ export interface IRequestContext {
    */
   rawBody?: Buffer;
   token?: string;
+  /**
+   * Actor information - identifies who is performing the request.
+   * Populated after authentication for audit logging, quota enforcement, etc.
+   */
+  actor?: IRequestActor;
 }
 
 /**

package/ts/core/interfaces.storage.ts

@@ -0,0 +1,130 @@
+import type { TRegistryProtocol } from './interfaces.core.js';
+
+/**
+ * Actor information from request context
+ */
+export interface IStorageActor {
+  userId?: string;
+  tokenId?: string;
+  ip?: string;
+  userAgent?: string;
+  orgId?: string;
+  sessionId?: string;
+}
+
+/**
+ * Metadata about the storage operation
+ */
+export interface IStorageMetadata {
+  /** Content type of the object */
+  contentType?: string;
+  /** Size in bytes */
+  size?: number;
+  /** Content digest (e.g., sha256:abc123) */
+  digest?: string;
+  /** Package/artifact name */
+  packageName?: string;
+  /** Version */
+  version?: string;
+}
+
+/**
+ * Context passed to storage hooks
+ */
+export interface IStorageHookContext {
+  /** Type of operation */
+  operation: 'put' | 'delete' | 'get';
+  /** Storage key/path */
+  key: string;
+  /** Protocol that triggered this operation */
+  protocol: TRegistryProtocol;
+  /** Actor who performed the operation (if known) */
+  actor?: IStorageActor;
+  /** Metadata about the object */
+  metadata?: IStorageMetadata;
+  /** Timestamp of the operation */
+  timestamp: Date;
+}
+
+/**
+ * Result from a beforePut hook that can modify the operation
+ */
+export interface IBeforePutResult {
+  /** Whether to allow the operation */
+  allowed: boolean;
+  /** Optional reason for rejection */
+  reason?: string;
+  /** Optional modified metadata */
+  metadata?: IStorageMetadata;
+}
+
+/**
+ * Result from a beforeDelete hook
+ */
+export interface IBeforeDeleteResult {
+  /** Whether to allow the operation */
+  allowed: boolean;
+  /** Optional reason for rejection */
+  reason?: string;
+}
+
+/**
+ * Storage event hooks for quota tracking, audit logging, cache invalidation, etc.
+ *
+ * @example
+ * ```typescript
+ * const quotaHooks: IStorageHooks = {
+ *   async beforePut(context) {
+ *     const quota = await getQuota(context.actor?.orgId);
+ *     const currentUsage = await getUsage(context.actor?.orgId);
+ *     if (currentUsage + (context.metadata?.size || 0) > quota) {
+ *       return { allowed: false, reason: 'Quota exceeded' };
+ *     }
+ *     return { allowed: true };
+ *   },
+ *
+ *   async afterPut(context) {
+ *     await updateUsage(context.actor?.orgId, context.metadata?.size || 0);
+ *     await auditLog('storage.put', context);
+ *   },
+ *
+ *   async afterDelete(context) {
+ *     await invalidateCache(context.key);
+ *   }
+ * };
+ * ```
+ */
+export interface IStorageHooks {
+  /**
+   * Called before storing an object.
+   * Return { allowed: false } to reject the operation.
+   * Use for quota checks, virus scanning, validation, etc.
+   */
+  beforePut?(context: IStorageHookContext): Promise<IBeforePutResult>;
+
+  /**
+   * Called after successfully storing an object.
+   * Use for quota tracking, audit logging, notifications, etc.
+   */
+  afterPut?(context: IStorageHookContext): Promise<void>;
+
+  /**
+   * Called before deleting an object.
+   * Return { allowed: false } to reject the operation.
+   * Use for preventing deletion of protected resources.
+   */
+  beforeDelete?(context: IStorageHookContext): Promise<IBeforeDeleteResult>;
+
+  /**
+   * Called after successfully deleting an object.
+   * Use for quota updates, audit logging, cache invalidation, etc.
+   */
+  afterDelete?(context: IStorageHookContext): Promise<void>;
+
+  /**
+   * Called after reading an object.
+   * Use for access logging, analytics, etc.
+   * Note: This is called even for cache hits.
+   */
+  afterGet?(context: IStorageHookContext): Promise<void>;
+}

package/ts/upstream/classes.baseupstream.ts

@@ -110,8 +110,18 @@ export abstract class BaseUpstream {
       return null;
     }
 
+    // Get applicable upstreams sorted by priority
+    const applicableUpstreams = this.getApplicableUpstreams(context.resource);
+
+    if (applicableUpstreams.length === 0) {
+      return null;
+    }
+
+    // Use the first applicable upstream's URL for cache key
+    const primaryUpstreamUrl = applicableUpstreams[0]?.url;
+
     // Check cache first
-    const cached = this.cache.get(context);
+    const cached = await this.cache.get(context, primaryUpstreamUrl);
     if (cached && !cached.stale) {
       return {
         success: true,
@@ -125,7 +135,7 @@ export abstract class BaseUpstream {
     }
 
     // Check for negative cache (recent 404)
-    if (this.cache.hasNegative(context)) {
+    if (await this.cache.hasNegative(context, primaryUpstreamUrl)) {
       return {
         success: false,
         status: 404,
@@ -136,13 +146,6 @@ export abstract class BaseUpstream {
       };
     }
 
-    // Get applicable upstreams sorted by priority
-    const applicableUpstreams = this.getApplicableUpstreams(context.resource);
-
-    if (applicableUpstreams.length === 0) {
-      return null;
-    }
-
     // If we have stale cache, return it immediately and revalidate in background
     if (cached?.stale && this.cacheConfig.staleWhileRevalidate) {
       // Fire and forget revalidation
@@ -173,18 +176,19 @@ export abstract class BaseUpstream {
 
         // Cache successful responses
         if (result.success && result.body) {
-          this.cache.set(
+          await this.cache.set(
             context,
             Buffer.isBuffer(result.body) ? result.body : Buffer.from(JSON.stringify(result.body)),
             result.headers['content-type'] || 'application/octet-stream',
             result.headers,
             upstream.id,
+            upstream.url,
           );
         }
 
         // Cache 404 responses
         if (result.status === 404) {
-          this.cache.setNegative(context, upstream.id);
+          await this.cache.setNegative(context, upstream.id, upstream.url);
         }
 
         return result;
@@ -210,15 +214,15 @@ export abstract class BaseUpstream {
   /**
    * Invalidate cache for a resource pattern.
    */
-  public invalidateCache(pattern: RegExp): number {
+  public async invalidateCache(pattern: RegExp): Promise<number> {
     return this.cache.invalidatePattern(pattern);
   }
 
   /**
    * Clear all cache entries.
    */
-  public clearCache(): void {
-    this.cache.clear();
+  public async clearCache(): Promise<void> {
+    await this.cache.clear();
   }
 
   /**
@@ -501,12 +505,13 @@ export abstract class BaseUpstream {
           );
 
           if (result.success && result.body) {
-            this.cache.set(
+            await this.cache.set(
               context,
               Buffer.isBuffer(result.body) ? result.body : Buffer.from(JSON.stringify(result.body)),
               result.headers['content-type'] || 'application/octet-stream',
               result.headers,
               upstream.id,
+              upstream.url,
             );
             return; // Successfully revalidated
           }