@bsv/overlay-express/dist/types/src/BanService.d.ts

BSV Blockchain Overlay Express

import { Db } from 'mongodb';
/**
 * Represents a banned record in the persistent ban list.
 * Bans survive server restarts, GASP re-syncs, and janitor runs.
 */
export interface BannedRecord {
    type: 'domain' | 'outpoint';
    /** For domain bans: the domain URL. For outpoint bans: "txid.outputIndex" */
    value: string;
    /** For outpoint bans, the associated domain (for reference) */
    domain?: string;
    /** Human-readable reason for the ban */
    reason?: string;
    /** When the ban was created */
    bannedAt: Date;
    /** Identity key of the admin who created the ban */
    bannedBy?: string;
}
/**
 * BanService provides a persistent ban list stored in MongoDB.
 *
 * When the Janitor or an admin removes a SHIP/SLAP token, the associated
 * domain or outpoint can be added to the ban list. The BanAwareLookupWrapper
 * checks this list before admitting new outputs, preventing GASP from
 * re-syncing previously removed stale tokens.
 */
export declare class BanService {
    private readonly bans;
    constructor(db: Db);
    /**
     * Sanitizes a value for use in MongoDB queries, preventing NoSQL injection.
     * Ensures the value is a plain string and rejects objects/arrays that could
     * contain MongoDB operators like $ne, $gt, etc.
     */
    private sanitize;
    /**
     * Creates indexes for efficient ban lookups.
     */
    ensureIndexes(): Promise<void>;
    /**
     * Bans a domain, preventing any SHIP/SLAP tokens referencing it from being stored.
     */
    banDomain(domain: string, reason?: string, bannedBy?: string): Promise<void>;
    /**
     * Removes a domain ban.
     */
    unbanDomain(domain: string): Promise<void>;
    /**
     * Checks if a domain is banned.
     */
    isDomainBanned(domain: string): Promise<boolean>;
    /**
     * Bans a specific outpoint (txid.outputIndex), preventing it from being re-admitted.
     */
    banOutpoint(txid: string, outputIndex: number, reason?: string, domain?: string, bannedBy?: string): Promise<void>;
    /**
     * Removes an outpoint ban.
     */
    unbanOutpoint(txid: string, outputIndex: number): Promise<void>;
    /**
     * Checks if a specific outpoint is banned.
     */
    isOutpointBanned(txid: string, outputIndex: number): Promise<boolean>;
    /**
     * Lists all bans, optionally filtered by type.
     */
    listBans(type?: 'domain' | 'outpoint'): Promise<BannedRecord[]>;
    /**
     * Removes a ban by type and value.
     */
    removeBan(type: 'domain' | 'outpoint', value: string): Promise<void>;
    /**
     * Returns ban statistics.
     */
    getStats(): Promise<{
        domainBans: number;
        outpointBans: number;
        totalBans: number;
    }>;
}
//# sourceMappingURL=BanService.d.ts.map