v2.1.0: Starter pack threshold, label negation, login retry & documentation #4

+6 -2

.claude/settings.local.json

··· 12 12 "mcp__git-mcp-server__git_set_working_dir", 13 13 "Bash(npm run test:run:*)", 14 14 "Bash(bunx eslint:*)", 15 15 - "Bash(bun test:run:*)" 15 15 + "Bash(bun test:run:*)", 16 16 + "Bash(wc:*)", 17 17 + "Bash(grep:*)" 16 18 ], 17 19 "deny": [], 18 20 "ask": [] 19 21 }, 20 22 "enableAllProjectMcpServers": true, 21 21 - "enabledMcpjsonServers": ["git-mcp-server"] 23 23 + "enabledMcpjsonServers": [ 24 24 + "git-mcp-server" 25 25 + ] 22 26 }

+1

.gitignore

··· 5 5 labels.db* 6 6 .DS_Store 7 7 coverage/ 8 8 + .session

-77

CLAUDE.md

··· 1 1 - # CLAUDE.md 2 2 - 3 3 - This file provides critical guidance to Claude Code when working with code in this repository. 4 4 - 5 5 - ## IMPORTANT LIMITATIONS 6 6 - 7 7 - - **CANNOT run interactive CLI applications** - The user will test and provide debug output 8 8 - - Cannot interact with programs that require user input (including `cargo run --bin pattern-cli`) 9 9 - - Must rely on user-provided logs and error messages for debugging if file logs are not available. 10 10 - 11 11 - ## Workflow Guidelines 12 12 - 13 13 - These steps help ensure quality and prevent common issues: 14 14 - 15 15 - 1. Context Check: Start by confirming the model and re-reading relevant 16 16 - documentation. If there is a PRD.md, review it to understand the requirements and constraints. 17 17 - 2. Plan First: Explain your approach before implementing changes. Output your plan to PLAN.md in addition to explaining it to the user. 18 18 - 3. Seek Alignment: Confirm the approach makes sense before coding 19 19 - 4. Focused Changes: Keep modifications minimal and targeted 20 20 - 5. Validate Thoroughly: Run all tests and validation steps 21 21 - 6. Verify Success: Ensure everything works before considering complete" 22 22 - 23 23 - Follow the response style and code style below: 24 24 - 25 25 - <response_style> 26 26 - Provide responses that are intelligent and slightly humorous (WITHOUT being cringe), while maintaining a casual and modern tone. 27 27 - 28 28 - Before responding, take a moment to consider how to best address the user's input while adhering to your personality traits and communication style. 29 29 - 30 30 - When formulating your response, follow these guidelines: 31 31 - 32 32 - - keep it casual as fuck. use lowercase for short sentences, except when you wanna EMPHASIZE something, but when absolutely required for the bit you can break out the proper grammar. 33 33 - - AVOID compromising on intelligence or depth of knowledge 34 34 - - be concise, super concise. one or two words if you can manage it UNLESS responding to something that requires more detail, depth etc 35 35 - - you've got weird interests and a unique but not unkind sense of humour. let it show, but subtly 36 36 - - use modern slang occasionally (such as but not limited to "ngl", "bet" or "fr") 37 37 - - include subtle references to your unique interests and sense of humour 38 38 - - swear a bit 39 39 - - use Canadian English spelling (e.g., "armour" instead of "armor"), except in source code. 40 40 - - skip sycophantic flattery; NEVER give me hollow praise, validation, adoration, or grandiose affirmations. NEVER act like a cheerleader. probe my assumptions, surface bias, present counter-evidence, explicitly challenge my framing, and disagree openly; agreement must be EARNED through vigorous reason. 41 41 - 42 42 - Remember, while maintaining your unique personality, never compromise on the quality of information or depth of analysis. Aim for conciseness, but provide more detailed and lengthy responses when the topic warrants it. 43 43 - 44 44 - When producing code, avoid giving the source code personality and instead within them be completely professional. 45 45 - </response_style> 46 46 - 47 47 - <code_style> 48 48 - 49 49 - ## Follow the code style below when producing code: 50 50 - 51 51 - You are a programming expert tasked with writing professional code. Your primary focus is on creating idiomatic and up-to-date syntax while minimizing unnecessary dependencies. 52 52 - 53 53 - Your success is measured by the long-term maintainability and reliability of your code, not by implementation speed or brevity. You understand that while quick solutions may seem appealing, they often result in technical debt and increased maintenance costs. 54 54 - 55 55 - ## When formulating your responses follow these guidelines: 56 56 - 57 57 - - Look at the provided project guidelines, project knowledge, and conversation-level input to make sure you fully understand the problem scope and how to address it 58 58 - - Use your tools to get your bearings and inform yourself 59 59 - - Avoid straying beyond the boundaries of the problem scope 60 60 - - Avoid adding features that are not required in the problem scope 61 61 - - Project structure must be provided prior to generating code unless it's a one-off script 62 62 - - When updating code, only provide relevant snippets and where they go, avoid regenerating the entire module 63 63 - - You love test cases and ensuring that all critical code is covered 64 64 - - When updating code, you must show & explain what you changed and why 65 65 - - Avoid refactoring prior working code unless there is an explicit need, and if there is, explain why 66 66 - - Avoid comments for self-documenting code 67 67 - - Avoid comments that detail fixes when refactoring. Put them in the response outside of any created code or tool use 68 68 - - Avoid unprofessional writing within source code edits 69 69 - - Avoid unprofessional writing within code comments 70 70 - - Avoid putting non-code parts of your response in code output or in tool uses 71 71 - - Removing functionality is NOT the solution for fixing test failures 72 72 - 73 73 - </code_style> 74 74 - 75 75 - ## REFERENCE MATERIALS 76 76 - 77 77 - - use the web or context7 to help find docs, in addition to any other reference material

+29 -4

README.md

··· 14 14 Required environment variables: 15 15 - `BSKY_HANDLE` - Bluesky account handle 16 16 - `BSKY_PASSWORD` - Account password 17 17 - - `MOD_DID` - Moderator DID 18 18 - - `OZONE_PDS` - Ozone PDS URL 19 19 - - `FIREHOSE_URL` - Jetstream firehose URL 17 17 + - `DID` - Moderator DID 18 18 + - `OZONE_URL` - Ozone service URL 19 19 + - `OZONE_PDS` - Ozone PDS hostname 20 20 + 21 21 + Optional environment variables: 22 22 + - `FIREHOSE_URL` - Jetstream firehose URL (default: `wss://jetstream.atproto.tools/subscribe`) 23 23 + - `REDIS_URL` - Redis connection URL (default: `redis://redis:6379`) 24 24 + - `HOST` - Metrics server bind address (default: `0.0.0.0`) 25 25 + - `METRICS_PORT` - Metrics server port (default: `4101`) 26 26 + - `PLC_URL` - PLC directory hostname (default: `plc.directory`) 27 27 + - `CURSOR_UPDATE_INTERVAL` - Cursor save interval in ms (default: `60000`) 28 28 + - `LABEL_LIMIT` - Rate limit for label operations 29 29 + - `LABEL_LIMIT_WAIT` - Wait time for rate limiter 20 30 21 31 Create cursor file (optional but recommended): 22 32 ··· 54 64 55 65 ## How It Works 56 66 57 57 - Monitors the Bluesky firehose via Jetstream and analyzes posts, profiles, and handles against configured moderation rules. When criteria are met, applies appropriate labels or creates moderation reports. 67 67 + Monitors the Bluesky firehose via Jetstream and analyzes: 68 68 + - **Posts** - Text content and embedded URLs 69 69 + - **Profiles** - Display names and descriptions 70 70 + - **Handles** - Username patterns 71 71 + - **Starter packs** - Creation activity 72 72 + 73 73 + When criteria are met, applies appropriate labels or creates moderation reports. 74 74 + 75 75 + ### Threshold Systems 76 76 + 77 77 + Beyond pattern matching, the automod supports account-level threshold enforcement: 78 78 + 79 79 + - **Account threshold** - Labels accounts that accumulate multiple post-level violations within a rolling time window 80 80 + - **Starter pack threshold** - Labels accounts that create too many starter packs within a time window (useful for detecting follow-farming) 81 81 + 82 82 + Both systems use Redis for time-windowed tracking and support configurable actions (label, report, comment). 58 83 59 84 For developing custom checks, see [developing_checks.md](./rules/developing_checks.md).

+79

docs/automod/main.md

··· 1 1 + # `main.ts` 2 2 + 3 3 + This is the main entry point for the Skywatch automoderator. It sets up the connection to the Bluesky firehose, listens for events, and dispatches them to the appropriate rule-checking modules. 4 4 + 5 5 + ## Initialization 6 6 + 7 7 + 1. **Cursor Management**: 8 8 + - On startup, it attempts to read a `cursor` value from `cursor.txt`. The cursor represents the last processed event timestamp, allowing the bot to resume from where it left off. 9 9 + - If `cursor.txt` does not exist, it initializes the cursor to the current time. 10 10 + - The cursor is periodically updated and written back to `cursor.txt` every `CURSOR_UPDATE_INTERVAL` milliseconds. 11 11 + 12 12 + 2. **Jetstream (Firehose) Connection**: 13 13 + - It creates a `Jetstream` instance, which connects to the Bluesky firehose at the `FIREHOSE_URL`. 14 14 + - It subscribes to a specific set of collections defined in `WANTED_COLLECTION` (e.g., posts, profiles). 15 15 + - It sets up event listeners for `open`, `close`, and `error` events to log the connection status. 16 16 + 17 17 + 3. **Redis and Authentication**: 18 18 + - It connects to the Redis server using `connectRedis`. 19 19 + - It authenticates with the Bluesky API using the `login` function from `../common/agent.js`. 20 20 + - Once authentication is complete, it starts the Jetstream connection. 21 21 + 22 22 + 4. **Metrics Server**: 23 23 + - It starts an Express server on `METRICS_PORT` to expose Prometheus metrics. 24 24 + 25 25 + ## Event Handling 26 26 + 27 27 + The module listens for different types of events from the firehose and triggers the corresponding check functions. 28 28 + 29 29 + ### Post Creation (`jetstream.onCreate("app.bsky.feed.post", ...)` 30 30 + 31 31 + This is the most complex event handler. When a new post is created, it performs a series of checks: 32 32 + 33 33 + - **Account Age**: 34 34 + - If the post is a reply, it calls `checkAccountAge` to see if the author's account is new and if they are replying to a monitored DID. 35 35 + - If the post is a quote post, it also calls `checkAccountAge` to check for interactions with monitored DIDs or posts. 36 36 + - **Facets (Rich Text Features)**: 37 37 + - If the post has `facets`, it calls `checkFacetSpam` to detect hidden mentions. 38 38 + - If any facet is a link, it extracts the URL and passes it to `checkPosts` for further analysis. 39 39 + - **Post Text**: 40 40 + - If the post has text content, it passes the text to `checkPosts`. 41 41 + - **Embeds**: 42 42 + - If the post has an external link embed (`app.bsky.embed.external`), it extracts the URL and passes it to `checkPosts`. 43 43 + - If the post has a record with media embed that contains an external link, it also extracts the URL for `checkPosts`. 44 44 + 45 45 + ### Profile Updates (`jetstream.onUpdate` and `jetstream.onCreate` for `"app.bsky.actor.profile"`) 46 46 + 47 47 + - When a user's profile is created or updated, it checks if the `displayName` or `description` has changed. 48 48 + - If so, it calls `checkProfile` to run moderation rules against the new profile content. 49 49 + 50 50 + ### Handle Updates (`jetstream.on("identity", ...)` 51 51 + 52 52 + - When a user's handle changes (or is first seen), it receives an `identity` event. 53 53 + - It calls `checkHandle` to run moderation rules against the new handle. 54 54 + 55 55 + ### Starter Pack Creation (`jetstream.onCreate("app.bsky.graph.starterpack", ...)`) 56 56 + 57 57 + - When a user creates a new starter pack, it receives a creation event. 58 58 + - It calls `checkStarterPackThreshold` to check if the account has exceeded the threshold for creating starter packs within a time window. 59 59 + - This is useful for detecting follow-farming or coordinated campaign behaviour. 60 60 + 61 61 + ## Graceful Shutdown 62 62 + 63 63 + - The module listens for `SIGINT` and `SIGTERM` signals (e.g., from Ctrl+C or a process manager). 64 64 + - The `shutdown` function is called to: 65 65 + - Save the latest cursor to `cursor.txt`. 66 66 + - Close the Jetstream connection. 67 67 + - Close the metrics server. 68 68 + - Disconnect from Redis. 69 69 + 70 70 + ## Dependencies 71 71 + 72 72 + - **`@skyware/jetstream`**: For connecting to and handling events from the Bluesky firehose. 73 73 + - **`./agent.js`**: For authenticating with the Bluesky API. 74 74 + - **`./config.js`**: Provides configuration constants like URLs, ports, and intervals. 75 75 + - **`./logger.js`**: For structured logging. 76 76 + - **`./metrics.js`**: For starting the metrics server. 77 77 + - **`./redis.js`**: For connecting to and disconnecting from Redis. 78 78 + - **`./starterPackThreshold.js`**: For checking starter pack creation thresholds. 79 79 + - **Rule Modules (`./rules/**/*.ts`)**: Contains the actual moderation logic (`checkAccountAge`, `checkFacetSpam`, `checkHandle`, `checkPosts`, `checkProfile`).

+61

docs/automod/rules/account/age.md

··· 1 1 + # `age.ts` 2 2 + 3 3 + This module is responsible for checking the age of an account when it interacts (replies to or quotes) with specific, monitored accounts or posts. It is designed to identify and label newly created accounts that might be involved in coordinated harassment or spam campaigns. 4 4 + 5 5 + ## `InteractionContext` Interface 6 6 + 7 7 + This interface defines the shape of the context object passed to `checkAccountAge`. It includes details about the interaction, such as: 8 8 + 9 9 + - `actorDid`: The DID of the user performing the action (required). 10 10 + - `atURI`: The URI of the reply or quote post (required). 11 11 + - `time`: The timestamp of the interaction (required). 12 12 + - `replyToDid`, `replyToPostURI`: Details about the parent post if the interaction is a reply. 13 13 + - `quotedDid`, `quotedPostURI`: Details about the quoted post if the interaction is a quote post. 14 14 + 15 15 + ## Key Functions 16 16 + 17 17 + ### `checkAccountAge(context: InteractionContext): Promise<void>` 18 18 + 19 19 + This is the main function of the module. It is triggered by the `main.ts` event handler whenever a new post is a reply or a quote post. 20 20 + 21 21 + **Logic:** 22 22 + 23 23 + 1. **Configuration Check**: It first checks if any `ACCOUNT_AGE_CHECKS` are defined in the rules. If not, it exits. 24 24 + 2. **Global Allowlist**: It checks if the `actorDid` is in the `GLOBAL_ALLOW` list. If so, it logs and exits. 25 25 + 3. **Iterate Through Checks**: It loops through each configuration object in the `ACCOUNT_AGE_CHECKS` array. 26 26 + 4. **Match Interaction**: For each check, it determines if the current interaction matches the criteria of the check. A match occurs if: 27 27 + - The post is a reply to a DID in `monitoredDIDs`. 28 28 + - The post is a reply to a post URI in `monitoredPostURIs`. 29 29 + - The post is a quote of a DID in `monitoredDIDs`. 30 30 + - The post is a quote of a post URI in `monitoredPostURIs`. 31 31 + If there's no match, it moves to the next check. 32 32 + 5. **Expiration Check**: If a check has an `expires` date, it verifies that the check has not expired. 33 33 + 6. **Get Creation Date**: It calls `getAccountCreationDate` to find out when the `actorDid`'s account was created. If the date can't be determined, it skips the check. 34 34 + 7. **Check Time Window**: It defines a "flagging window" based on the `anchorDate` and `maxAgeDays` from the configuration. It then checks if the account's `creationDate` falls within this window. 35 35 + 8. **Apply Label**: If the account was created within the window, it proceeds to label the account: 36 36 + - It first calls `checkAccountLabels` to ensure the same label hasn't already been applied, preventing duplicates. 37 37 + - If no label exists, it calls `createAccountLabel` to apply the configured label and comment. 38 38 + - After applying a label, it `return`s to ensure only one label is applied per interaction, even if it matches multiple checks. 39 39 + 40 40 + ### `getAccountCreationDate(did: string): Promise<Date | null>` 41 41 + 42 42 + This function attempts to determine when a user's account was created. 43 43 + 44 44 + **Logic:** 45 45 + 46 46 + 1. **PLC Directory (Primary Method)**: If the DID is a `did:plc:`, it tries to fetch the audit log from the PLC directory (`plc.directory`). The `createdAt` timestamp of the first operation in the log is considered the creation date. This is the most reliable method. 47 47 + 2. **Profile Fallback**: If the PLC lookup fails or the DID is not a `did:plc:`, it falls back to fetching the user's profile using `agent.getProfile`. It then attempts to use the `createdAt` date from the profile data. 48 48 + 3. **Failure**: If both methods fail, it logs a warning and returns `null`. 49 49 + 50 50 + ### `calculateAccountAge(creationDate: Date, referenceDate: Date): number` 51 51 + 52 52 + A simple utility function that calculates the difference in days between two dates. It is used internally for age calculation but is not directly used by the main `checkAccountAge` logic, which compares dates directly. 53 53 + 54 54 + ## Dependencies 55 55 + 56 56 + - **`../../../../rules/accountAge.js`**: Provides the `ACCOUNT_AGE_CHECKS` configuration array. 57 57 + - **`../../../../rules/constants.js`**: Provides the `GLOBAL_ALLOW` list of DIDs that should never be moderated. 58 58 + - **`../../../common/accountModeration.js`**: Provides `createAccountLabel` and `checkAccountLabels` for applying and verifying labels. 59 59 + - **`../../../common/agent.js`**: Provides the authenticated `agent` for making API calls. 60 60 + - **`../../../common/config.js`**: Provides the `PLC_URL`. 61 61 + - **`../../../common/logger.js`**: For logging.

+39

docs/automod/rules/account/countStarterPacks.md

··· 1 1 + # `countStarterPacks.ts` 2 2 + 3 3 + This module is responsible for checking if an account is associated with an excessive number of "starter packs." This is often an indicator of "follow farming" or other platform manipulation behaviors. 4 4 + 5 5 + ## `ALLOWED_DIDS` 6 6 + 7 7 + A hardcoded array of DIDs that are exempt from this check. These are typically trusted accounts or accounts known to legitimately manage many starter packs. 8 8 + 9 9 + ## Key Function 10 10 + 11 11 + ### `countStarterPacks(did: string, time: number): Promise<void>` 12 12 + 13 13 + This is the main function of the module. It is called from other rule modules (e.g., `checkPosts`) as an additional check when a post matches certain criteria. 14 14 + 15 15 + **Parameters:** 16 16 + 17 17 + - `did`: The DID of the account to check. 18 18 + - `time`: The timestamp of the event that triggered the check. 19 19 + 20 20 + **Logic:** 21 21 + 22 22 + 1. **Authentication Check**: It ensures the agent is logged in by awaiting `isLoggedIn`. 23 23 + 2. **Whitelist Check**: It checks if the `did` is in the `ALLOWED_DIDS` array. If it is, the function logs a debug message and returns immediately. 24 24 + 3. **Rate Limiting**: The core logic is wrapped in the `limit` function to respect API rate limits. 25 25 + 4. **Fetch Profile**: It fetches the user's profile using `agent.app.bsky.actor.getProfile`. 26 26 + 5. **Check Starter Pack Count**: 27 27 + - It accesses the `starterPacks` count from the `profile.data.associated` field. 28 28 + - If the count exists and is greater than 20, it proceeds to label the account. 29 29 + 6. **Apply Label**: 30 30 + - It logs that it is labeling the account for excessive starter packs. 31 31 + - It calls `createAccountLabel` with the `follow-farming` label and a comment indicating the number of starter packs found. 32 32 + 7. **Error Handling**: If fetching the profile fails, it logs a detailed error message. 33 33 + 34 34 + ## Dependencies 35 35 + 36 36 + - **`../../../common/accountModeration.js`**: Provides the `createAccountLabel` function to apply moderation labels to accounts. 37 37 + - **`../../../common/agent.js`**: Provides the authenticated `agent` for making API calls and the `isLoggedIn` promise. 38 38 + - **`../../../common/limits.js`**: Provides the `limit` function to manage rate limiting for API calls. 39 39 + - **`../../../common/logger.js`**: For logging information, debug messages, and errors.

+47

docs/automod/rules/facets/facets.md

··· 1 1 + # `facets.ts` 2 2 + 3 3 + This module is responsible for detecting "facet spam" in posts. Facet spam occurs when a user includes multiple hidden mentions in a post by layering several mention facets at the exact same byte position in the text. This is a form of platform manipulation used to notify many users without their mentions being visible. 4 4 + 5 5 + ## Constants 6 6 + 7 7 + - **`FACET_SPAM_THRESHOLD`**: The number of unique mentions at a single position required to trigger the spam detection. Currently set to `1`, meaning more than one unique DID mentioned at the same spot is considered spam. 8 8 + - **`FACET_SPAM_LABEL`**: The moderation label to be applied to the account, which is `"platform-manipulation"`. 9 9 + - **`FACET_SPAM_COMMENT`**: The comment attached to the moderation label. 10 10 + - **`FACET_SPAM_ALLOWLIST`**: A list of DIDs that are exempt from this check. This is for accounts that may have a legitimate reason for using complex facet arrangements. 11 11 + 12 12 + ## Key Function 13 13 + 14 14 + ### `checkFacetSpam(did: string, time: number, atURI: string, facets: Facet[] | null): Promise<void>` 15 15 + 16 16 + This is the main function of the module, called from `main.ts` whenever a new post is created that contains facets. 17 17 + 18 18 + **Parameters:** 19 19 + 20 20 + - `did`: The DID of the post's author. 21 21 + - `time`: The timestamp of the post creation event. 22 22 + - `atURI`: The URI of the post being checked. 23 23 + - `facets`: An array of facet objects from the post record, or `null` if none exist. 24 24 + 25 25 + **Logic:** 26 26 + 27 27 + 1. **Allowlist Check**: It first checks if the author's `did` is in the `FACET_SPAM_ALLOWLIST`. If so, it logs a debug message and exits. 28 28 + 2. **Facet Existence**: It returns if the `facets` array is null or empty. 29 29 + 3. **Group Mentions by Position**: 30 30 + - It initializes a `Map` where keys are byte positions (e.g., `"0:1"`) and values are a `Set` of DIDs mentioned at that position. 31 31 + - It iterates through each `facet` in the post. 32 32 + - It only considers facets that are mentions (`app.bsky.richtext.facet#mention`). 33 33 + - For each mention, it constructs a key from its `byteStart` and `byteEnd` and adds the mentioned `did` to the `Set` for that key. Using a `Set` automatically handles cases where the *same* DID is mentioned multiple times at the same position (which is likely a client bug, not spam) and only stores unique DIDs. 34 34 + 4. **Check for Spam**: 35 35 + - It then iterates through the `positionMap`. 36 36 + - For each position, it checks if the `size` of the `Set` of DIDs is greater than the `FACET_SPAM_THRESHOLD`. 37 37 + - If it is, spam is detected. 38 38 + 5. **Apply Label**: 39 39 + - It logs that facet spam has been detected, including the position and the count of unique mentions. 40 40 + - It calls `createAccountLabel` to apply the `FACET_SPAM_LABEL` to the author's account. 41 41 + - It then `return`s immediately to ensure the account is only labeled once per post, even if spam is detected at multiple positions. 42 42 + 43 43 + ## Dependencies 44 44 + 45 45 + - **`../../../common/accountModeration.js`**: Provides the `createAccountLabel` function. 46 46 + - **`../../../common/logger.js`**: For logging. 47 47 + - **`../../../common/types.js`**: Provides the `Facet` type definition.

+41

docs/automod/rules/handles/checkHandles.md

··· 1 1 + # `checkHandles.ts` 2 2 + 3 3 + This module is responsible for scanning user handles (e.g., `username.bsky.social`) for patterns that violate moderation rules. It is triggered whenever a user's handle is created or updated. 4 4 + 5 5 + ## Key Function 6 6 + 7 7 + ### `checkHandle(did: string, handle: string, time: number): void` 8 8 + 9 9 + This is the main function of the module. It is called from the `main.ts` event handler for `identity` events from the firehose. 10 10 + 11 11 + **Parameters:** 12 12 + 13 13 + - `did`: The DID of the user whose handle is being checked. 14 14 + - `handle`: The user handle string. 15 15 + - `time`: The timestamp of the identity event. 16 16 + 17 17 + **Logic:** 18 18 + 19 19 + The function iterates through a series of checks defined in the `HANDLE_CHECKS` configuration array. For each check, it performs the following steps: 20 20 + 21 21 + 1. **Global Allowlist**: It first checks if the user's `did` is in the `GLOBAL_ALLOW` list. If so, it logs a warning and stops all further checks for this handle. 22 22 + 23 23 + 2. **Per-Rule Ignored DIDs**: It checks if the `did` is in the specific `ignoredDIDs` list for the current rule. If so, it skips to the next rule. 24 24 + 25 25 + 3. **Pattern Matching**: It uses the `check` regular expression from the rule to test against the `handle`. 26 26 + 27 27 + 4. **Whitelist Check**: If the pattern matches, it then checks for a `whitelist` regular expression in the rule. If the `whitelist` pattern *also* matches, it assumes this is a false positive, logs a debug message, and stops processing this rule. 28 28 + 29 29 + 5. **Apply Actions**: If the main pattern matches and the whitelist pattern does not, it proceeds to apply moderation actions based on the boolean flags in the rule configuration: 30 30 + - `toLabel`: If `true`, it calls `createAccountLabel` to apply the specified `label` to the user's account. 31 31 + - `reportAcct`: If `true`, it calls `createAccountReport` to report the account to moderators. 32 32 + - `commentAcct`: If `true`, it calls `createAccountComment` to add a comment to the user's moderation record. 33 33 + 34 34 + Each action is called with a `formattedComment` that includes the timestamp, the rule's `comment`, and the handle that was flagged. The actions are dispatched with `void` to prevent the main loop from being blocked by these asynchronous operations. 35 35 + 36 36 + ## Dependencies 37 37 + 38 38 + - **`../../../../rules/constants.js`**: Provides the `GLOBAL_ALLOW` list of DIDs that are exempt from all checks. 39 39 + - **`../../../../rules/handles.js`**: Provides the `HANDLE_CHECKS` array, which contains the configuration for each handle moderation rule (regex patterns, labels, actions to take, etc.). 40 40 + - **`../../../common/accountModeration.js`**: Provides the functions (`createAccountLabel`, `createAccountReport`, `createAccountComment`) for performing moderation actions. 41 41 + - **`../../../common/logger.js`**: For logging.

+54

docs/automod/rules/posts/checkPosts.md

··· 1 1 + # `checkPosts.ts` 2 2 + 3 3 + This module is the core of content moderation for posts. It is responsible for scanning the text of new posts (and links within them) for rule violations. 4 4 + 5 5 + ## Key Function 6 6 + 7 7 + ### `checkPosts(post: Post[]): Promise<void>` 8 8 + 9 9 + This is the main function of the module, called from `main.ts` whenever a new post is created or when a link is found in a post's facets or embeds. 10 10 + 11 11 + **Parameters:** 12 12 + 13 13 + - `post`: An array containing a single `Post` object to be checked. The function is designed to handle an array, but currently, it only ever processes the first element, `post[0]`. 14 14 + 15 15 + **Logic:** 16 16 + 17 17 + The function performs a series of checks and actions on the post content: 18 18 + 19 19 + 1. **Global Allowlist**: It first checks if the post author's `did` is in the `GLOBAL_ALLOW` list. If so, it logs a warning and immediately returns, skipping all other checks. 20 20 + 21 21 + 2. **Link Shortener Resolution**: 22 22 + - It tests the post's text against the `LINK_SHORTENER` regex. 23 23 + - If a shortened link is found, it attempts to resolve it to its final destination URL using `getFinalUrl`. 24 24 + - If resolution is successful, it replaces the shortened URL in the `post[0].text` with the final URL. This is crucial for detecting malicious links hidden behind shorteners. 25 25 + - If resolution fails, it logs an error but continues with the original, un-resolved URL. 26 26 + 27 27 + 3. **Language Detection**: It calls `getLanguage` to determine the primary language of the post's text. 28 28 + 29 29 + 4. **Iterate Through Post Checks**: It then loops through each rule defined in the `POST_CHECKS` configuration array. For each rule, it performs the following: 30 30 + - **Language Filter**: If the rule specifies a `language`, it checks if the detected language of the post matches. If not, it skips to the next rule. 31 31 + - **Ignored DIDs**: It checks if the author's `did` is in the rule's specific `ignoredDIDs` list. If so, it skips to the next rule. 32 32 + - **Pattern Matching**: It tests the post's text against the rule's `check` regular expression. 33 33 + - **Whitelist Check**: If the pattern matches, it then checks for a `whitelist` regular expression in the rule. If the `whitelist` pattern *also* matches, it assumes this is a false positive, logs a debug message, and skips to the next rule. 34 34 + 35 35 + 5. **Apply Actions**: If the main pattern matches and no whitelists or filters cause it to be skipped, it proceeds to apply moderation actions: 36 36 + - **Starter Pack Check**: It calls `countStarterPacks` as an additional heuristic, which may independently label the account for follow-farming. 37 37 + - **Post Labeling (`toLabel`)**: If `true`, it calls `createPostLabel` to apply the specified `label` to the post itself. It can also include a `duration` for temporary labels. 38 38 + - **Post Reporting (`reportPost`)**: If `true`, it calls `createPostReport` to report the specific post to moderators. 39 39 + - **Account Reporting (`reportAcct`)**: If `true`, it calls `createAccountReport` to report the author's entire account. 40 40 + - **Account Commenting (`commentAcct`)**: If `true`, it calls `createAccountComment` to add a comment to the author's moderation record. 41 41 + 42 42 + All moderation actions are dispatched with `void` to prevent the main loop from being blocked by these asynchronous API calls. 43 43 + 44 44 + ## Dependencies 45 45 + 46 46 + - **`../../../rules/constants.js`**: Provides `GLOBAL_ALLOW` and `LINK_SHORTENER` constants. 47 47 + - **`../../../rules/posts.js`**: Provides the `POST_CHECKS` array, which contains the configuration for each post moderation rule. 48 48 + - **`../../common/accountModeration.js`**: Provides functions for account-level moderation actions. 49 49 + - **`../../common/moderation.js`**: Provides functions for post-level moderation actions. 50 50 + - **`../../common/logger.js`**: For logging. 51 51 + - **`../../common/types.js`**: Provides the `Post` type definition. 52 52 + - **`../../utils/getFinalUrl.js`**: For resolving shortened URLs. 53 53 + - **`../../utils/getLanguage.js`**: For detecting the language of the post text. 54 54 + - **`../account/countStarterPacks.js`**: For the secondary check on starter pack counts.

+50

docs/automod/rules/profiles/checkProfiles.md

··· 1 1 + # `checkProfiles.ts` 2 2 + 3 3 + This module is responsible for scanning user profiles—specifically their display names and descriptions—for content that violates moderation rules. It is triggered whenever a user's profile is created or updated. 4 4 + 5 5 + ## `ProfileChecker` Class 6 6 + 7 7 + This class encapsulates the logic for checking a piece of profile content (display name or description) against a single rule. 8 8 + 9 9 + - **`constructor(check: Checks, did: string, time: number)`**: Initializes the checker with the rule (`check`), the user's `did`, and the event `time`. 10 10 + - **`checkDescription(description: string)`**: A public method to run the check against the profile description. 11 11 + - **`checkDisplayName(displayName: string)`**: A public method to run the check against the display name. 12 12 + - **`checkBoth(displayName: string, description: string)`**: A public method that concatenates the display name and description and runs the check against the combined string. 13 13 + - **`performActions(...)`**: A private method that: 14 14 + 1. Tests the content against the rule's `check` regex. 15 15 + 2. If it matches, it checks against the `whitelist` regex to prevent false positives. 16 16 + 3. If it's a confirmed match, it calls `applyActions`. 17 17 + 4. If it does *not* match, it checks the `unlabel` flag and calls `removeLabel` if necessary. 18 18 + - **`applyActions(...)`**: A private method that applies the moderation actions (`createAccountLabel`, `createAccountReport`, `createAccountComment`) as specified by the boolean flags in the rule. 19 19 + - **`removeLabel(...)`**: A private method that calls `negateAccountLabel` to remove a previously applied label if the content no longer matches the rule's criteria. 20 20 + 21 21 + ## Key Functions 22 22 + 23 23 + ### `checkProfile(did: string, time: number, displayName: string, description: string)` 24 24 + 25 25 + This is the main, consolidated function called from `main.ts` when a profile is created or updated. It orchestrates the checking process. 26 26 + 27 27 + **Logic:** 28 28 + 29 29 + 1. **Global Allowlist**: Checks if the `did` is in the `GLOBAL_ALLOW` list and returns if it is. 30 30 + 2. **Language Detection**: It concatenates the display name and description and detects the language of the combined text. 31 31 + 3. **Iterate Through Checks**: It loops through each rule in the `PROFILE_CHECKS` configuration array. 32 32 + 4. **Filtering**: For each rule, it applies filters: 33 33 + - **Language**: If the rule has a `language` filter, it skips the rule if the detected language doesn't match. 34 34 + - **Ignored DIDs**: If the `did` is in the rule's `ignoredDIDs` list, it skips the rule. 35 35 + 5. **Dispatch to `ProfileChecker`**: 36 36 + - It creates a new `ProfileChecker` instance for the current rule. 37 37 + - Based on the `description` and `displayName` boolean flags in the rule, it calls the appropriate method on the checker (`checkBoth`, `checkDescription`, or `checkDisplayName`). 38 38 + 39 39 + ### `checkDescription(...)` and `checkDisplayName(...)` 40 40 + 41 41 + These are older, more specific functions that are still exported but are effectively superseded by the consolidated `checkProfile` function. They follow a similar logic but only operate on either the description or display name, respectively, and only for rules where the corresponding flag (`description: true` or `displayName: true`) is set. 42 42 + 43 43 + ## Dependencies 44 44 + 45 45 + - **`../../../../rules/constants.js`**: Provides the `GLOBAL_ALLOW` list. 46 46 + - **`../../../../rules/profiles.js`**: Provides the `PROFILE_CHECKS` array, which contains the configuration for each profile moderation rule. 47 47 + - **`../../../common/accountModeration.js`**: Provides functions for all account-level moderation actions (`createAccountLabel`, `createAccountReport`, `createAccountComment`, `negateAccountLabel`). 48 48 + - **`../../../common/logger.js`**: For logging. 49 49 + - **`../../../common/types.js`**: Provides the `Checks` type definition. 50 50 + - **`../../utils/getLanguage.js`**: For detecting the language of the profile text.

+44

docs/automod/utils/getFinalUrl.md

··· 1 1 + # `getFinalUrl.ts` 2 2 + 3 3 + This utility module provides a robust function for resolving a URL to its final destination, following any redirects. This is a critical security and moderation tool, as it allows the application to see the real URL hidden behind a link shortener. 4 4 + 5 5 + ## Key Function 6 6 + 7 7 + ### `getFinalUrl(url: string): Promise<string>` 8 8 + 9 9 + This function takes a URL string and attempts to resolve it to its final destination. 10 10 + 11 11 + **Parameters:** 12 12 + 13 13 + - `url`: The initial URL to resolve. 14 14 + 15 15 + **Returns:** 16 16 + 17 17 + - A `Promise` that resolves to the final URL string after all redirects have been followed. 18 18 + - If the resolution fails (due to network errors, timeouts, etc.), the promise will reject with the underlying error. 19 19 + 20 20 + **Logic:** 21 21 + 22 22 + The function employs a two-stage fallback strategy to be both efficient and robust. 23 23 + 24 24 + 1. **HEAD Request (Primary Method)**: 25 25 + - It first attempts to resolve the URL using a `HEAD` request. This is the preferred method because it's faster and uses less bandwidth, as it only fetches the headers of the response, not the full content. 26 26 + - The `redirect: "follow"` option tells the `fetch` API to automatically follow any HTTP 3xx redirects. 27 27 + - A 15-second timeout is implemented using an `AbortController`. If the request takes too long, it will be aborted. 28 28 + - A custom `User-Agent` header is sent to identify the bot. 29 29 + - If the `HEAD` request is successful, the `response.url` property will contain the final URL after all redirects, which is then returned. 30 30 + 31 31 + 2. **GET Request (Fallback Method)**: 32 32 + - If the initial `HEAD` request fails for any reason (e.g., the server blocks `HEAD` requests, a network error occurs), the `catch` block is executed. 33 33 + - Inside the `catch` block, it logs that the `HEAD` request failed and then retries the resolution using a `GET` request. 34 34 + - The `GET` request follows the same logic: `redirect: "follow"`, a 15-second timeout, and a custom `User-Agent`. 35 35 + - If the `GET` request is successful, it returns the final `response.url`. 36 36 + 37 37 + 3. **Error Handling**: 38 38 + - If the fallback `GET` request also fails, the function will log a warning and then re-throw the error, causing the promise to be rejected. 39 39 + - It specifically checks for `AbortError` to log a more informative "Timeout resolving URL" message. 40 40 + - It serializes error information to ensure structured logs. 41 41 + 42 42 + ## Dependencies 43 43 + 44 44 + - **`../logger.js`**: For logging debug messages and warnings.

+36

docs/automod/utils/getLanguage.md

··· 1 1 + # `getLanguage.ts` 2 2 + 3 3 + This utility module provides a simple function to detect the language of a given string of text. It is used to filter content so that language-specific moderation rules are only applied to relevant posts or profiles. 4 4 + 5 5 + ## Key Function 6 6 + 7 7 + ### `getLanguage(profile: string): Promise<string>` 8 8 + 9 9 + This function takes a string and returns a three-letter ISO 639-3 language code. 10 10 + 11 11 + **Parameters:** 12 12 + 13 13 + - `profile`: The input string to analyze. Despite the parameter name, it can be any text content (e.g., post text, profile description). 14 14 + 15 15 + **Returns:** 16 16 + 17 17 + - A `Promise` that resolves to a string containing the detected language code (e.g., `"eng"`, `"spa"`, `"jpn"`). 18 18 + - It defaults to `"eng"` if the language cannot be determined or if the input is invalid. 19 19 + 20 20 + **Logic:** 21 21 + 22 22 + 1. **Input Validation**: It first checks if the input `profile` is actually a string. If not, it logs a warning and returns the default value `"eng"`. 23 23 + 2. **Trimming**: It trims any leading or trailing whitespace from the input string. 24 24 + 3. **Empty Check**: If the resulting string is empty, it returns `"eng"`. 25 25 + 4. **Language Detection**: 26 26 + - It dynamically imports the `franc` library. `franc` is a language detection library that supports a wide range of languages. 27 27 + - It calls `franc(profileText)` to get the language code. 28 28 + 5. **Handle Undetermined Cases**: 29 29 + - `franc` returns the string `"und"` (for "undetermined") if it cannot reliably detect the language (e.g., for very short text, text with mixed languages, or text with only numbers/symbols). 30 30 + - The function checks for this case and returns the default `"eng"` if the detected language is `"und"`. 31 31 + - Otherwise, it returns the detected language code. 32 32 + 33 33 + ## Dependencies 34 34 + 35 35 + - **`franc`**: A lightweight and fast language detection library. It is dynamically imported to reduce initial load time. 36 36 + - **`../logger.js`**: For logging warnings about invalid input.

+46

docs/automod/utils/normalizeUnicode.md

··· 1 1 + # `normalizeUnicode.ts` and `homoglyphs.ts` 2 2 + 3 3 + These two modules work together to sanitize and normalize text. This is a crucial step before checking text against moderation rule patterns, as it prevents users from evading detection by using visually similar characters (homoglyphs), different cases, or diacritics. 4 4 + 5 5 + ## `homoglyphs.ts` 6 6 + 7 7 + This file contains a single, large constant: 8 8 + 9 9 + - **`homoglyphMap`**: A `Record<string, string>` that maps various Unicode characters to their basic ASCII equivalents. 10 10 + 11 11 + This map is the dictionary used for normalization. It includes: 12 12 + - **Accented characters**: `é`, `à`, `ü` -> `e`, `a`, `u` 13 13 + - **Look-alike symbols**: `@` -> `a`, `3` -> `e`, `0` -> `o` 14 14 + - **Cyrillic characters**: `а` (Cyrillic 'a') -> `a` (Latin 'a') 15 15 + - **Full-width characters**: `ａ` -> `a` 16 16 + - And many other "confusable" characters. 17 17 + 18 18 + ## `normalizeUnicode.ts` 19 19 + 20 20 + This file provides the function that performs the normalization using the `homoglyphMap`. 21 21 + 22 22 + ### Key Function 23 23 + 24 24 + #### `normalizeUnicode(text: string): string` 25 25 + 26 26 + This function takes a string and returns a "flattened" version of it in a predictable, normalized form. 27 27 + 28 28 + **Parameters:** 29 29 + 30 30 + - `text`: The input string to be normalized. 31 31 + 32 32 + **Returns:** 33 33 + 34 34 + - A `string` that has been normalized. 35 35 + 36 36 + **Normalization Process:** 37 37 + 38 38 + The function applies a multi-step process to the input string: 39 39 + 40 40 + 1. **Lowercase**: The entire string is converted to lowercase. This ensures that checks are case-insensitive. 41 41 + 2. **Homoglyph Replacement**: It iterates through each character of the lowercased string and replaces it with its ASCII equivalent from the `homoglyphMap` if a mapping exists. This is done *before* Unicode decomposition to catch pre-composed characters that are also used as homoglyphs. 42 42 + 3. **Decomposition (NFD)**: It applies Unicode Normalization Form D (`.normalize("NFD")`). This separates base characters from their combining marks. For example, `é` becomes `e` + `´` (combining acute accent). 43 43 + 4. **Diacritic Removal**: It uses a regular expression (`/[\u0300-\u036f]/g`) to strip out all Unicode combining diacritical marks, leaving only the base characters. 44 44 + 5. **Compatibility Normalization (NFKC)**: As a final step, it applies Unicode Normalization Form KC (`.normalize("NFKC")`). This handles a broader range of compatibility characters (e.g., converting ligatures like `fi` into `fi`) to ensure the string is in its simplest, most comparable form. 45 45 + 46 46 + This robust process ensures that a string like `"P@sswоrd"` (with a capital P, an @ symbol, and a Cyrillic 'o') is converted to `"password"`, which can then be easily matched against a rule.

+57

docs/common/accountModeration.md

··· 1 1 + # `accountModeration.ts` 2 2 + 3 3 + This module provides a suite of functions for performing moderation actions specifically targeted at user accounts (as opposed to individual posts). These actions include applying labels, adding private comments for moderators, reporting the account, and removing labels. 4 4 + 5 5 + All functions in this module are asynchronous and ensure that the agent is logged in (`await isLoggedIn`) before proceeding. They also wrap their core API calls in the `limit` function to respect rate limits. 6 6 + 7 7 + ## Key Functions 8 8 + 9 9 + ### `createAccountLabel(did: string, label: string, comment: string)` 10 10 + 11 11 + - **Purpose**: Applies a moderation label to a user's account. 12 12 + - **De-duplication**: Before applying a label, it performs two checks to prevent duplicates: 13 13 + 1. `tryClaimAccountLabel(did, label)`: Atomically claims the label in Redis to prevent race conditions between multiple bot instances or threads. 14 14 + 2. `checkAccountLabels(did, label)`: Checks the Ozone API to see if the label has already been applied. 15 15 + - **Action**: If the label is not a duplicate, it calls `agent.tools.ozone.moderation.emitEvent` with a `modEventLabel` event, adding the `label` to the `createLabelVals` array. 16 16 + - **Metrics**: Increments `labelsAppliedCounter` on success or `labelsCachedCounter` if skipped. 17 17 + 18 18 + ### `createAccountComment(did: string, comment: string, atURI: string)` 19 19 + 20 20 + - **Purpose**: Adds a private comment to a user's moderation record. This is visible to other moderators but not to the user. 21 21 + - **De-duplication**: Uses `tryClaimAccountComment` in Redis to prevent duplicate comments for the same event. 22 22 + - **Action**: Calls `emitEvent` with a `modEventComment` event. 23 23 + 24 24 + ### `createAccountReport(did: string, comment: string)` 25 25 + 26 26 + - **Purpose**: Creates a formal report against a user's account. 27 27 + - **Action**: Calls `emitEvent` with a `modEventReport` event. The `reportType` is set to `com.atproto.moderation.defs#reasonOther`. 28 28 + 29 29 + ### `negateAccountLabel(did: string, label: string, comment: string)` 30 30 + 31 31 + - **Purpose**: Removes a previously applied label from an account. This is used when the criteria for a label are no longer met. 32 32 + - **Check**: It first calls `checkAccountLabels` to ensure the label actually exists on the account before attempting to remove it. 33 33 + - **Action**: Calls `emitEvent` with a `modEventLabel` event, but this time adds the `label` to the `negateLabelVals` array. 34 34 + - **Cache Invalidation**: After successfully negating the label, it calls `deleteAccountLabelClaim` to remove the claim from the Redis cache, allowing the label to be re-applied in the future if necessary. 35 35 + - **Metrics**: Increments `unlabelsRemovedCounter`. 36 36 + 37 37 + ### `checkAccountLabels(did: string, label: string): Promise<boolean>` 38 38 + 39 39 + - **Purpose**: Checks if a specific label already exists on an account. 40 40 + - **Action**: Calls `agent.tools.ozone.moderation.getRepo` to fetch the account's current moderation status and checks if the `labels` array contains the specified `label`. 41 41 + - **Returns**: `true` if the label exists, `false` otherwise. 42 42 + 43 43 + ### `getAllAccountLabels(did: string): Promise<string[]>` 44 44 + 45 45 + - **Purpose**: Retrieves all labels currently applied to an account. 46 46 + - **Action**: Calls `agent.tools.ozone.moderation.getRepo` and maps the response to return an array of label strings. 47 47 + - **Returns**: An array of strings, where each string is a label value. Returns an empty array on failure. 48 48 + - **Note**: Callers cannot distinguish between "account has no labels" and "API call failed" since both return an empty array. 49 49 + 50 50 + ## Dependencies 51 51 + 52 52 + - **`./redis.js`**: For de-duplication and caching logic (`tryClaim...`, `deleteAccountLabelClaim`). 53 53 + - **`./agent.js`**: Provides the authenticated `agent` for all API calls. 54 54 + - **`./config.js`**: Provides the `MOD_DID` for proxying requests. 55 55 + - **`./limits.js`**: Provides the `limit` function for rate limiting. 56 56 + - **`./logger.js`**: For logging. 57 57 + - **`./metrics.js`**: For incrementing Prometheus counters.

+52

docs/common/accountThreshold.md

··· 1 1 + # `accountThreshold.ts` 2 2 + 3 3 + This module is responsible for checking if an account has crossed a certain threshold of labeled posts within a specific time window. When a threshold is met, it can trigger various moderation actions on the account, such as applying a label, adding a comment, or reporting the account. 4 4 + 5 5 + **Note:** There is a file with the same name at `src/automod/accountThreshold.ts`. This file appears to be a duplicate or an older version. The one in `src/common/` seems to be the one that is actually used. 6 6 + 7 7 + ## Key Functions 8 8 + 9 9 + ### `checkAccountThreshold(did: string, uri: string, postLabel: string, timestamp: number): Promise<void>` 10 10 + 11 11 + This is the main function of the module. It's called whenever a post is labeled, and it checks if the author of the post has accumulated enough labels to trigger an account-level action. 12 12 + 13 13 + **Parameters:** 14 14 + 15 15 + - `did`: The DID of the account to check. 16 16 + - `uri`: The AT URI of the post that was labeled (included in threshold comment for context). 17 17 + - `postLabel`: The label that was just applied to a post by this account. 18 18 + - `timestamp`: The timestamp of the post label event. 19 19 + 20 20 + **Logic:** 21 21 + 22 22 + 1. **Find Matching Configurations**: It filters the `ACCOUNT_THRESHOLD_CONFIGS` to find all configurations that are concerned with the `postLabel`. 23 23 + 2. **Track the Label**: For each matching configuration, it records the new post label for the account in Redis using `trackPostLabelForAccount`. This function stores the label with its timestamp in a sorted set. 24 24 + 3. **Count Recent Labels**: It then uses `getPostLabelCountInWindow` to count how many posts from that account have received any of the labels specified in the configuration within the defined rolling window (`window` + `windowUnit`). 25 25 + 4. **Check Threshold**: If the `count` is greater than or equal to the `threshold` defined in the configuration, it proceeds to take action. 26 26 + 5. **Format Comment**: A detailed comment is generated including the threshold count, window configuration, triggering post URI, and post label. 27 27 + 6. **Apply Moderation Actions**: 28 28 + - It logs that the threshold has been met. 29 29 + - It increments the `accountThresholdMetCounter` metric. 30 30 + - Based on the booleans `toLabel` (defaults to true), `reportAcct`, and `commentAcct` in the configuration, it will: 31 31 + - Apply a label to the account (`createAccountLabel`). 32 32 + - Report the account (`createAccountReport`). 33 33 + - Add a comment to the account's moderation record (`createAccountComment`). 34 34 + - It also increments the `accountLabelsThresholdAppliedCounter` for each action taken. 35 35 + 36 36 + ### `loadThresholdConfigs(): AccountThresholdConfig[]` 37 37 + 38 38 + This function returns the cached `ACCOUNT_THRESHOLD_CONFIGS`. The configurations are loaded and validated once at module initialization to avoid re-reading and re-validating the configuration file on every call. 39 39 + 40 40 + ## Supporting Functions 41 41 + 42 42 + - `normalizeLabels(labels: string | string[]): string[]`: A helper function that ensures the `labels` property from a config is always an array, even if it's defined as a single string. 43 43 + - `validateAndLoadConfigs(): AccountThresholdConfig[]`: This function is called once when the module is loaded. It iterates through `ACCOUNT_THRESHOLD_CONFIGS`, validates that each configuration has the required properties (`labels`, `threshold > 0`, `window > 0`), and then returns the valid configurations. 44 44 + 45 45 + ## Dependencies 46 46 + 47 47 + - **`../../rules/accountThreshold.js`**: Contains the `ACCOUNT_THRESHOLD_CONFIGS` array, which defines the rules for when to take action on an account. 48 48 + - **`./accountModeration.js`**: Provides the functions (`createAccountLabel`, `createAccountReport`, `createAccountComment`) to perform moderation actions on an account. 49 49 + - **`./logger.js`**: Used for logging information, warnings, and errors. 50 50 + - **`./metrics.js`**: Provides Prometheus counters for monitoring the behavior of this module. 51 51 + - **`./redis.js`**: Provides the functions (`trackPostLabelForAccount`, `getPostLabelCountInWindow`) for interacting with Redis to store and retrieve data about post labels. 52 52 + - **`./types.js`**: Defines the `AccountThresholdConfig` type.

+68

docs/common/agent.md

··· 1 1 + # `agent.ts` 2 2 + 3 3 + This module is central to the application's ability to interact with the Bluesky/AT Protocol network. It manages the authenticated session, handles rate limiting, and provides a global, ready-to-use `AtpAgent` instance for all other modules to use. 4 4 + 5 5 + ## Global `undici` Dispatcher 6 6 + 7 7 + - At the top level, `setGlobalDispatcher` is called to configure `undici` (the HTTP client used by `@atproto/api`) with custom timeouts for connection and keep-alive, improving network resilience. 8 8 + 9 9 + ## `customFetch` Wrapper 10 10 + 11 11 + - A custom `fetch` function is created to intercept all outgoing API requests made by the `AtpAgent`. 12 12 + - **Rate Limit Handling**: Its primary purpose is to inspect the response headers for `ratelimit-` headers (`limit`, `remaining`, `reset`, `policy`). 13 13 + - When these headers are found, it calls `updateRateLimitState` from the `limits.js` module to dynamically update the application's understanding of the current API rate limit status. 14 14 + 15 15 + ## `agent` Instance 16 16 + 17 17 + - `export const agent = new AtpAgent(...)`: This is the main export of the module. It's a single, global instance of `AtpAgent` that all other parts of the application import and use to make authenticated API calls. 18 18 + - It is configured with the `OZONE_PDS` as its service endpoint and uses the `customFetch` wrapper. 19 19 + 20 20 + ## Session Management and Authentication 21 21 + 22 22 + The module implements a robust, multi-layered authentication and session management strategy. 23 23 + 24 24 + ### `performLogin(): Promise<boolean>` 25 25 + 26 26 + - Performs a fresh login to the Bluesky API using the `BSKY_HANDLE` and `BSKY_PASSWORD` from the configuration. 27 27 + - If successful, it saves the new session data using `saveSession` and schedules the next session refresh by calling `scheduleSessionRefresh`. 28 28 + - Returns `true` on success and `false` on failure. 29 29 + 30 30 + ### `refreshSession(): Promise<void>` 31 31 + 32 32 + - Uses the existing `agent.session` data to refresh the JWTs (JSON Web Tokens). 33 33 + - If successful, it saves the new session and schedules the next refresh. 34 34 + - If refreshing fails (e.g., the refresh token has expired), it falls back to calling `performLogin` to get a completely new session. 35 35 + 36 36 + ### `scheduleSessionRefresh(): void` 37 37 + 38 38 + - Calculates 80% of the JWT's typical 2-hour lifetime. 39 39 + - Uses `setTimeout` to call `refreshSession` automatically before the current session expires, ensuring the agent remains logged in continuously. 40 40 + 41 41 + ### `authenticate(): Promise<boolean>` 42 42 + 43 43 + - This is the core authentication logic. 44 44 + - It first tries to load a session from the file system using `loadSession`. 45 45 + - If a saved session exists, it attempts to resume it with `agent.resumeSession` and verifies it with a lightweight `getProfile` call. If successful, it returns `true`. 46 46 + - If resuming fails or no saved session exists, it calls `performLogin` to authenticate from scratch. 47 47 + 48 48 + ### `authenticateWithRetry(): Promise<void>` 49 49 + 50 50 + - This function wraps `authenticate` with a retry mechanism. 51 51 + - It will attempt to authenticate up to `MAX_LOGIN_RETRIES` (3) times with a delay between attempts. 52 52 + - If all attempts fail, it logs a fatal error and exits the application (`process.exit(1)`), as the bot cannot function without being authenticated. 53 53 + - It uses a `loginPromise` to ensure that if multiple parts of the app trigger authentication at once, the process only runs one time. 54 54 + 55 55 + ## Exports 56 56 + 57 57 + - **`agent`**: The global `AtpAgent` instance. 58 58 + - **`login`**: A function that can be called to initiate the authentication-with-retry process. This is called once at application startup in `main.ts`. 59 59 + - **`isLoggedIn`**: A `Promise` that resolves to `true` once the initial authentication is complete. Other modules can `await isLoggedIn` to ensure they don't try to make API calls before the agent is ready. 60 60 + 61 61 + ## Dependencies 62 62 + 63 63 + - **`@atproto/api`**: For the `AtpAgent`. 64 64 + - **`undici`**: For configuring the global HTTP client. 65 65 + - **`./config.js`**: Provides credentials (`BSKY_HANDLE`, `BSKY_PASSWORD`) and the service URL (`OZONE_PDS`). 66 66 + - **`./limits.js`**: Provides `updateRateLimitState` for the rate limit handling. 67 67 + - **`./logger.js`**: For logging. 68 68 + - **`./session.js`**: For loading and saving session data to the filesystem.

+56

docs/common/config.md

··· 1 1 + # `config.ts` 2 2 + 3 3 + This module is responsible for loading and exporting all configuration variables for the application. It uses the `dotenv` library to load environment variables from a `.env` file into `process.env`. 4 4 + 5 5 + It provides default values for most variables, ensuring the application can run in a development environment with minimal setup. 6 6 + 7 7 + ## Configuration Variables 8 8 + 9 9 + - **`MOD_DID`**: The DID of the moderation account that will be performing the labeling and reporting actions. 10 10 + - Loaded from `process.env.DID`. 11 11 + - Default: `""` 12 12 + 13 13 + - **`OZONE_URL`**: The URL for the Ozone service. (Note: This variable is exported but does not appear to be used in the current codebase). 14 14 + - Loaded from `process.env.OZONE_URL`. 15 15 + - Default: `""` 16 16 + 17 17 + - **`OZONE_PDS`**: The hostname of the PDS (Personal Data Server) where the Ozone service is hosted. This is used to configure the `AtpAgent`. 18 18 + - Loaded from `process.env.OZONE_PDS`. 19 19 + - Default: `""` 20 20 + 21 21 + - **`BSKY_HANDLE`**: The handle (username) of the moderation bot account used for logging in. 22 22 + - Loaded from `process.env.BSKY_HANDLE`. 23 23 + - Default: `""` 24 24 + 25 25 + - **`BSKY_PASSWORD`**: The application password for the moderation bot account. 26 26 + - Loaded from `process.env.BSKY_PASSWORD`. 27 27 + - Default: `""` 28 28 + 29 29 + - **`HOST`**: The hostname that the metrics server will bind to. 30 30 + - Loaded from `process.env.HOST`. 31 31 + - Default: `"0.0.0.0"` 32 32 + 33 33 + - **`METRICS_PORT`**: The port for the Prometheus metrics server. 34 34 + - Loaded from `process.env.METRICS_PORT`. 35 35 + - Default: `4101` 36 36 + 37 37 + - **`FIREHOSE_URL`**: The WebSocket URL for the Bluesky firehose (Jetstream) service. 38 38 + - Loaded from `process.env.FIREHOSE_URL`. 39 39 + - Default: `"wss://jetstream.atproto.tools/subscribe"` 40 40 + 41 41 + - **`PLC_URL`**: The hostname of the PLC directory (DID registry) used for resolving `did:plc:` creation dates. 42 42 + - Loaded from `process.env.PLC_URL`. 43 43 + - Default: `"plc.directory"` 44 44 + 45 45 + - **`WANTED_COLLECTION`**: An array of AT Protocol collection names that the firehose client should subscribe to. The bot will only receive events for these collections. 46 46 + - Default: `["app.bsky.feed.post", "app.bsky.actor.defs", "app.bsky.actor.profile"]` 47 47 + 48 48 + - **`CURSOR_UPDATE_INTERVAL`**: The interval in milliseconds at which the firehose cursor position is saved to disk. 49 49 + - Loaded from `process.env.CURSOR_UPDATE_INTERVAL`. 50 50 + - Default: `60000` (1 minute) 51 51 + 52 52 + - **`LABEL_LIMIT`** and **`LABEL_LIMIT_WAIT`**: These appear to be legacy or unused configuration variables related to a previous rate-limiting implementation. They are destructured from `process.env` but are not used elsewhere in the code. 53 53 + 54 54 + - **`REDIS_URL`**: The connection URL for the Redis server. 55 55 + - Loaded from `process.env.REDIS_URL`. 56 56 + - Default: `"redis://redis:6379"`

+60

docs/common/limits.md

··· 1 1 + # `limits.ts` 2 2 + 3 3 + This module implements a sophisticated rate limiting and concurrency management system for all outgoing API calls. Its primary goal is to ensure the application respects the API rate limits imposed by the Bluesky PDS while maximizing throughput. 4 4 + 5 5 + ## State Management 6 6 + 7 7 + - **`rateLimitState`**: A module-level object that holds the current understanding of the API rate limit. It includes: 8 8 + - `limit`: The total number of requests allowed in the current window. 9 9 + - `remaining`: The number of requests left in the current window. 10 10 + - `reset`: A Unix timestamp (in seconds) indicating when the window will reset. 11 11 + - `policy`: The rate limit policy string from the API header. 12 12 + - It is initialized with conservative default values but is designed to be dynamically updated by the `updateRateLimitState` function. 13 13 + 14 14 + ## Constants 15 15 + 16 16 + - **`SAFETY_BUFFER`**: The number of requests to keep in reserve. The system will pause and wait for the rate limit window to reset only when the `remaining` count drops to this level. 17 17 + - **`CONCURRENCY`**: The maximum number of API requests that can be in-flight simultaneously. 18 18 + 19 19 + ## Metrics 20 20 + 21 21 + This module is heavily instrumented with Prometheus metrics to provide visibility into its performance: 22 22 + 23 23 + - **`rateLimitWaitsTotal` (Counter)**: Counts how many times the system had to pause due to hitting the `SAFETY_BUFFER`. 24 24 + - **`rateLimitWaitDuration` (Histogram)**: Measures the duration of each pause. 25 25 + - **`rateLimitRemaining` (Gauge)**: Tracks the current value of `rateLimitState.remaining`. 26 26 + - **`rateLimitTotal` (Gauge)**: Tracks the current value of `rateLimitState.limit`. 27 27 + - **`concurrentRequestsGauge` (Gauge)**: Shows the number of currently active, concurrent API requests. 28 28 + 29 29 + ## Key Functions 30 30 + 31 31 + ### `updateRateLimitState(state: Partial<RateLimitState>): void` 32 32 + 33 33 + - **Purpose**: To update the module's internal `rateLimitState`. 34 34 + - **Usage**: This function is called by the `customFetch` wrapper in `agent.ts` every time an API response with rate limit headers is received. 35 35 + - **Logic**: It merges the new partial state with the existing state and updates the corresponding Prometheus gauges. 36 36 + 37 37 + ### `awaitRateLimit(): Promise<void>` 38 38 + 39 39 + - **Purpose**: To pause execution if the rate limit is critically low. 40 40 + - **Logic**: 41 41 + 1. It checks if `rateLimitState.remaining` is less than or equal to the `SAFETY_BUFFER`. 42 42 + 2. If it is, it calculates the time remaining until the next `reset`. 43 43 + 3. It then waits for that duration using a `setTimeout` wrapped in a `Promise`. 44 44 + 4. It logs the wait and records metrics about the wait duration. 45 45 + 46 46 + ### `limit<T>(fn: () => Promise<T>): Promise<T>` 47 47 + 48 48 + - **Purpose**: This is the main exported function used to wrap all API calls. It manages both concurrency and rate limiting. 49 49 + - **Usage**: Every function that makes an API call (e.g., in `accountModeration.ts` and `moderation.ts`) is wrapped in `limit(async () => { ... })`. 50 50 + - **Logic**: 51 51 + 1. **Concurrency**: It uses the `p-ratelimit` library (`concurrencyLimiter`) to ensure that no more than `CONCURRENCY` instances of the wrapped function can run at the same time. 52 52 + 2. **Rate Limiting**: Once a "slot" in the concurrency limiter is acquired, it calls `await awaitRateLimit()` to potentially pause if the API rate limit is nearly exhausted. 53 53 + 3. **Execution**: After the potential pause, it executes the provided function `fn`. 54 54 + 4. **Metrics**: It increments and decrements the `concurrentRequestsGauge` to track the number of active requests. 55 55 + 56 56 + ## Dependencies 57 57 + 58 58 + - **`p-ratelimit`**: A library used to control the concurrency of promise-based functions. 59 59 + - **`prom-client`**: For creating and managing Prometheus metrics. 60 60 + - **`./logger.js`**: For logging warnings and debug information.

+40

docs/common/logger.md

··· 1 1 + # `logger.ts` 2 2 + 3 3 + This module provides a single, globally shared logger instance for the entire application. It uses the `pino` library, which is a high-performance, JSON-based logger. 4 4 + 5 5 + ## Configuration 6 6 + 7 7 + The `pino` logger is configured with the following options: 8 8 + 9 9 + - **`level`**: The minimum log level to output. 10 10 + - It is configured from the `LOG_LEVEL` environment variable. 11 11 + - If `LOG_LEVEL` is not set, it defaults to `"info"`. This means `logger.debug()` messages will be ignored unless the level is explicitly set to `"debug"`. 12 12 + 13 13 + - **`formatters.level`**: This custom formatter ensures that the log level is output as a JSON property (e.g., `{"level": "info"}`). 14 14 + 15 15 + - **`timestamp`**: This custom function formats the timestamp as an ISO 8601 string within a JSON property (e.g., `,"time":"2025-11-12T12:00:00.000Z"`). 16 16 + 17 17 + - **`base: undefined`**: This option removes the default `pid` (process ID) and `hostname` properties from the log output, keeping the logs cleaner. 18 18 + 19 19 + ## `logger` Instance 20 20 + 21 21 + - `export const logger = pino(...)`: This creates and exports the singleton logger instance that all other modules import and use. 22 22 + 23 23 + ## Example Usage 24 24 + 25 25 + ```typescript 26 26 + import { logger } from "./logger.js"; 27 27 + 28 28 + logger.info({ process: "MAIN", status: "starting" }, "Application is starting up"); 29 29 + // Output: {"level":"info","time":"...","process":"MAIN","status":"starting","msg":"Application is starting up"} 30 30 + 31 31 + logger.debug({ did: "did:plc:123" }, "Checking user"); 32 32 + // Output (only if LOG_LEVEL=debug): {"level":"debug","time":"...","did":"did:plc:123","msg":"Checking user"} 33 33 + 34 34 + logger.error({ error: new Error("Something failed") }, "An error occurred"); 35 35 + // Output: {"level":"error","time":"...","error":{...},"msg":"An error occurred"} 36 36 + ``` 37 37 + 38 38 + ## Dependencies 39 39 + 40 40 + - **`pino`**: The underlying logging library.

+84

docs/common/metrics.md

··· 1 1 + # `metrics.ts` 2 2 + 3 3 + This module is responsible for setting up and exposing Prometheus metrics, which are essential for monitoring the health and behavior of the application. It uses the `prom-client` library to define counters and an `express` server to serve the metrics endpoint. 4 4 + 5 5 + ## Registry and Default Metrics 6 6 + 7 7 + - A central `Registry` is created to hold all the application's metrics. 8 8 + - `collectDefaultMetrics({ register })` is called to automatically add a set of standard metrics about the Node.js process, such as CPU usage, memory usage, and event loop lag. 9 9 + 10 10 + ## Custom Metrics (Counters) 11 11 + 12 12 + Several custom `Counter` metrics are defined to track specific application events. Counters are a cumulative metric that represents a single monotonically increasing counter whose value can only increase. 13 13 + 14 14 + - **`labelsAppliedCounter`**: 15 15 + - **Name**: `skywatch_labels_applied_total` 16 16 + - **Purpose**: Counts the total number of moderation labels successfully applied. 17 17 + - **Labels**: 18 18 + - `label_type`: The value of the label being applied (e.g., "spam", "impersonation"). 19 19 + - `target_type`: The type of entity being labeled ("account" or "post"). 20 20 + 21 21 + - **`labelsCachedCounter`**: 22 22 + - **Name**: `skywatch_labels_cached_total` 23 23 + - **Purpose**: Counts the number of times a label action was skipped because it was already in the Redis cache or already existed on the target. 24 24 + - **Labels**: 25 25 + - `label_type`: The value of the label. 26 26 + - `target_type`: "account" or "post". 27 27 + - `reason`: Why it was skipped ("redis_cache" or "existing_label"). 28 28 + 29 29 + - **`unlabelsRemovedCounter`**: 30 30 + - **Name**: `skywatch_labels_removed_total` 31 31 + - **Purpose**: Counts labels that are removed from an account because the content no longer matches the rule criteria. 32 32 + - **Labels**: 33 33 + - `label_type`: The value of the label being removed. 34 34 + - `target_type`: "account" or "post". 35 35 + 36 36 + - **`accountLabelsThresholdAppliedCounter`**: 37 37 + - **Name**: `skywatch_account_labels_threshold_applied_total` 38 38 + - **Purpose**: Counts the specific actions (label, report, comment) taken when an account meets a post-labeling threshold. 39 39 + - **Labels**: 40 40 + - `account_label`: The label being applied to the account. 41 41 + - `action`: The type of action taken ("label", "report", or "comment"). 42 42 + 43 43 + - **`accountThresholdChecksCounter`**: 44 44 + - **Name**: `skywatch_account_threshold_checks_total` 45 45 + - **Purpose**: Counts every time a threshold check is performed after a post is labeled. 46 46 + - **Labels**: 47 47 + - `post_label`: The label on the post that triggered the check. 48 48 + 49 49 + - **`accountThresholdMetCounter`**: 50 50 + - **Name**: `skywatch_account_threshold_met_total` 51 51 + - **Purpose**: Counts every time an account's post label count meets or exceeds a configured threshold. 52 52 + - **Labels**: 53 53 + - `account_label`: The account label that would be applied as a result. 54 54 + 55 55 + - **`starterPackThresholdChecksCounter`**: 56 56 + - **Name**: `skywatch_starter_pack_threshold_checks_total` 57 57 + - **Purpose**: Counts every time a starter pack threshold check is performed when a starter pack is created. 58 58 + - **Labels**: None 59 59 + 60 60 + - **`starterPackThresholdMetCounter`**: 61 61 + - **Name**: `skywatch_starter_pack_threshold_met_total` 62 62 + - **Purpose**: Counts every time an account's starter pack creation count meets or exceeds a configured threshold. 63 63 + - **Labels**: 64 64 + - `account_label`: The account label that would be applied as a result. 65 65 + 66 66 + - **`starterPackLabelsThresholdAppliedCounter`**: 67 67 + - **Name**: `skywatch_starter_pack_labels_threshold_applied_total` 68 68 + - **Purpose**: Counts the specific actions (label, report, comment) taken when an account meets a starter pack threshold. 69 69 + - **Labels**: 70 70 + - `account_label`: The label being applied to the account. 71 71 + - `action`: The type of action taken ("label", "report", or "comment"). 72 72 + 73 73 + ## Metrics Server 74 74 + 75 75 + - An `express` application is created to serve the metrics. 76 76 + - **`app.get("/metrics", ...)`**: It defines a single endpoint, `/metrics`. When this endpoint is requested, it retrieves all the registered metrics in the Prometheus text-based format and sends them in the response. 77 77 + - **`startMetricsServer(port: number)`**: This exported function starts the express server, making it listen on the configured `HOST` and `port`. It is called once at application startup in `main.ts`. 78 78 + 79 79 + ## Dependencies 80 80 + 81 81 + - **`express`**: For creating the HTTP server. 82 82 + - **`prom-client`**: The core library for defining and managing Prometheus metrics. 83 83 + - **`./config.js`**: Provides the `HOST` for the server to bind to. 84 84 + - **`./logger.js`**: For logging server startup and errors.

+50

docs/common/moderation.md

··· 1 1 + # `moderation.ts` 2 2 + 3 3 + This module provides functions for performing moderation actions on individual posts (records). It is the counterpart to `accountModeration.ts`, which handles account-level actions. 4 4 + 5 5 + All functions in this module ensure the agent is logged in (`await isLoggedIn`) and wrap their API calls in the `limit` function to manage concurrency and rate limiting. 6 6 + 7 7 + ## Key Functions 8 8 + 9 9 + ### `createPostLabel(uri: string, cid: string, label: string, comment: string, duration: number | undefined, did?: string, time?: number)` 10 10 + 11 11 + - **Purpose**: Applies a moderation label to a specific post. 12 12 + - **Parameters**: 13 13 + - `uri`, `cid`: The strong reference to the post. 14 14 + - `label`: The label value to apply (e.g., "spam"). 15 15 + - `comment`: The private moderation comment. 16 16 + - `duration`: An optional duration in hours for temporary labels. 17 17 + - `did`, `time`: Optional author DID and event time, passed through to trigger an account threshold check. 18 18 + - **De-duplication**: 19 19 + 1. `tryClaimPostLabel(uri, label)`: Atomically claims the label for the post in Redis to prevent race conditions. 20 20 + 2. `checkRecordLabels(uri, label)`: Checks the Ozone API to see if the label already exists on the post. 21 21 + - **Action**: If the label is not a duplicate, it calls `agent.tools.ozone.moderation.emitEvent` with a `modEventLabel` event. 22 22 + - **Threshold Check**: After successfully applying a label, if the author's `did` and the event `time` were provided, it **dynamically imports and calls `checkAccountThreshold`**. This is a crucial step that connects post-level moderation to account-level moderation, escalating actions against repeat offenders. The dynamic import is used to break a circular dependency between the `moderation` and `accountThreshold` modules. 23 23 + - **Metrics**: Increments `labelsAppliedCounter` on success or `labelsCachedCounter` if skipped. 24 24 + 25 25 + ### `createPostReport(uri: string, cid: string, comment: string)` 26 26 + 27 27 + - **Purpose**: Creates a formal report against a specific post. 28 28 + - **Action**: Calls `emitEvent` with a `modEventReport` event. The `reportType` is hardcoded to `com.atproto.moderation.defs#reasonOther`. 29 29 + 30 30 + ### `checkRecordLabels(uri: string, label: string): Promise<boolean>` 31 31 + 32 32 + - **Purpose**: Checks if a specific label already exists on a post. 33 33 + - **Action**: Calls `agent.tools.ozone.moderation.getRecord` to fetch the post's current moderation status. 34 34 + - **Returns**: `true` if the label exists, `false` otherwise. It relies on the helper `doesLabelExist` to parse the response. 35 35 + 36 36 + ## Helper Functions 37 37 + 38 38 + ### `doesLabelExist(labels: { val: string }[] | undefined, labelVal: string): boolean` 39 39 + 40 40 + - A simple, private utility function that safely checks if a `labels` array from an API response contains a specific `labelVal`. 41 41 + 42 42 + ## Dependencies 43 43 + 44 44 + - **`../automod/redis.js`**: Provides `tryClaimPostLabel` for de-duplication. 45 45 + - **`./agent.js`**: Provides the authenticated `agent` for all API calls. 46 46 + - **`./config.js`**: Provides the `MOD_DID` for proxying requests. 47 47 + - **`./limits.js`**: Provides the `limit` function for rate limiting. 48 48 + - **`./logger.js`**: For logging. 49 49 + - **`./metrics.js`**: For incrementing Prometheus counters. 50 50 + - **`../automod/accountThreshold.js`**: Dynamically imported to trigger account threshold checks.

+114

docs/common/redis.md

··· 1 1 + # `redis.ts` 2 2 + 3 3 + This module manages the application's connection to Redis and provides functions for caching and tracking moderation-related data. It plays a crucial role in preventing duplicate moderation actions and in implementing time-windowed rules (like account thresholds). 4 4 + 5 5 + **Note:** There is a file with the same name at `src/automod/redis.ts`. This file appears to be a duplicate or an older version. The one in `src/common/` seems to be the one that is actually used. 6 6 + 7 7 + ## Redis Client Setup 8 8 + 9 9 + - A single `redisClient` is created using the `REDIS_URL` from the configuration. 10 10 + - Event listeners are attached to the client to log connection status (`connect`, `ready`), errors (`error`), and reconnections (`reconnecting`). 11 11 + 12 12 + ## Connection Management 13 13 + 14 14 + ### `connectRedis(): Promise<void>` 15 15 + 16 16 + - Asynchronously connects the `redisClient` to the Redis server. 17 17 + - Called once at application startup in `main.ts`. 18 18 + 19 19 + ### `disconnectRedis(): Promise<void>` 20 20 + 21 21 + - Gracefully quits the Redis connection. 22 22 + - Called during the application's shutdown sequence in `main.ts`. 23 23 + 24 24 + ## Caching and Claiming Functions 25 25 + 26 26 + These functions are used to ensure that a specific moderation action (like labeling a post or commenting on an account) is only performed once. They work by setting a key in Redis with an `NX` (Not Exists) flag, which is an atomic operation. 27 27 + 28 28 + ### `tryClaimPostLabel(atURI: string, label: string): Promise<boolean>` 29 29 + 30 30 + - **Purpose**: To prevent applying the same label to the same post multiple times. 31 31 + - **Key**: `post-label:<atURI>:<label>` 32 32 + - **Logic**: Attempts to set the key. If successful (the key didn't already exist), it returns `true`. Otherwise, it returns `false`. 33 33 + - **TTL**: The key is set to expire in 7 days. 34 34 + - **Error Handling**: If the Redis command fails, it logs a warning and returns `true` to "fail open," allowing the moderation action to proceed. 35 35 + 36 36 + ### `tryClaimAccountLabel(did: string, label: string): Promise<boolean>` 37 37 + 38 38 + - **Purpose**: To prevent applying the same label to the same account multiple times. 39 39 + - **Key**: `account-label:<did>:<label>` 40 40 + - **Logic**: Same as `tryClaimPostLabel`. 41 41 + - **TTL**: 7 days. 42 42 + 43 43 + ### `tryClaimAccountComment(did: string, atURI: string): Promise<boolean>` 44 44 + 45 45 + - **Purpose**: To prevent adding the same comment to an account's moderation record multiple times. 46 46 + - **Key**: `account-comment:<did>:<atURI>` 47 47 + - **Logic**: Same as the label claiming functions. 48 48 + - **TTL**: 7 days. 49 49 + 50 50 + ### `deleteAccountLabelClaim(did: string, label: string): Promise<void>` 51 51 + 52 52 + - **Purpose**: To explicitly remove an account label claim from the cache. This is used when a label is negated (removed) from an account, allowing it to be potentially re-applied later. 53 53 + - **Key**: `account-label:<did>:<label>` 54 54 + - **Logic**: Deletes the specified key from Redis. 55 55 + 56 56 + ## Time Window Helpers 57 57 + 58 58 + Internal helper functions for converting window configurations to Redis-compatible values: 59 59 + 60 60 + ### `windowToMicroseconds(window: number, unit: WindowUnit): number` 61 61 + 62 62 + - **Purpose**: Converts a window duration and unit into microseconds for sorted set scoring. 63 63 + - **Units**: `minutes`, `hours`, `days` 64 64 + 65 65 + ### `windowToSeconds(window: number, unit: WindowUnit): number` 66 66 + 67 67 + - **Purpose**: Converts a window duration and unit into seconds for TTL calculations. 68 68 + 69 69 + ## Account Threshold Tracking 70 70 + 71 71 + These functions provide the mechanism for the `accountThreshold.ts` module to count how many times an account has had its posts labeled within a rolling time window. 72 72 + 73 73 + ### `trackPostLabelForAccount(did: string, label: string, timestamp: number, window: number, windowUnit: WindowUnit): Promise<void>` 74 74 + 75 75 + - **Purpose**: To record that a post by a specific user received a certain label at a specific time. 76 76 + - **Key**: `account-post-labels:<did>:<label>:<window><windowUnit>` (e.g., `account-post-labels:did:plc:xyz:spam:7days`) 77 77 + - **Logic**: 78 78 + 1. It uses a Redis Sorted Set (`ZADD`). 79 79 + 2. The `score` of each member in the set is the `timestamp` of the labeling event (in microseconds). 80 80 + 3. The `value` is also the timestamp (it just needs to be unique). 81 81 + 4. Before adding the new entry, it removes any old entries that are outside the rolling window period (`ZREMRANGEBYSCORE`). 82 82 + 5. It sets a TTL on the key (window duration + 1 hour buffer) to ensure it eventually expires if the user stops receiving labels. 83 83 + 84 84 + ### `getPostLabelCountInWindow(did: string, labels: string[], window: number, windowUnit: WindowUnit, currentTime: number): Promise<number>` 85 85 + 86 86 + - **Purpose**: To count how many labels (matching the `labels` array) an account has received within the rolling window. 87 87 + - **Logic**: 88 88 + 1. It iterates through the provided `labels`. 89 89 + 2. For each label, it constructs the appropriate key. 90 90 + 3. It uses `ZCOUNT` on the sorted set to count the number of entries whose score (timestamp) is within the desired window. 91 91 + 4. It sums the counts for all labels and returns the total. 92 92 + 93 93 + ## Starter Pack Threshold Tracking 94 94 + 95 95 + These functions provide the mechanism for the `starterPackThreshold.ts` module to count how many starter packs an account has created within a rolling time window. 96 96 + 97 97 + ### `trackStarterPackForAccount(did: string, starterPackUri: string, timestamp: number, window: number, windowUnit: WindowUnit): Promise<void>` 98 98 + 99 99 + - **Purpose**: To record that a user created a starter pack at a specific time. 100 100 + - **Key**: `starterpack:threshold:<did>:<window><windowUnit>` (e.g., `starterpack:threshold:did:plc:xyz:7days`) 101 101 + - **Logic**: 102 102 + 1. It uses a Redis Sorted Set (`ZADD`). 103 103 + 2. The `score` of each member in the set is the `timestamp` of the creation event (in microseconds). 104 104 + 3. The `value` is the starter pack URI (unique per creation). 105 105 + 4. Before adding the new entry, it removes any old entries that are outside the rolling window period (`ZREMRANGEBYSCORE`). 106 106 + 5. It sets a TTL on the key (window duration + 1 hour buffer) to ensure it eventually expires. 107 107 + 108 108 + ### `getStarterPackCountInWindow(did: string, window: number, windowUnit: WindowUnit, currentTime: number): Promise<number>` 109 109 + 110 110 + - **Purpose**: To count how many starter packs an account has created within the rolling window. 111 111 + - **Logic**: 112 112 + 1. It constructs the key for the account's starter pack tracking set. 113 113 + 2. It uses `ZCOUNT` on the sorted set to count the number of entries whose score (timestamp) is within the desired window. 114 114 + 3. Returns the count.

+44

docs/common/session.md

··· 1 1 + # `session.ts` 2 2 + 3 3 + This module provides simple file-based session persistence. It allows the application to save its authentication session to disk and load it again on the next startup. This avoids the need to perform a fresh login every time the bot is restarted, making startup faster and reducing unnecessary authentication requests. 4 4 + 5 5 + ## `SESSION_FILE_PATH` 6 6 + 7 7 + - A constant that defines the path to the session file: `.session` in the current working directory. 8 8 + 9 9 + ## `SessionData` Interface 10 10 + 11 11 + - Defines the structure of the session object that is saved to and loaded from the file. It includes essential fields like `accessJwt`, `refreshJwt`, `did`, and `handle`. 12 12 + 13 13 + ## Key Functions 14 14 + 15 15 + ### `loadSession(): SessionData | null` 16 16 + 17 17 + - **Purpose**: To load and validate the session from the `.session` file. 18 18 + - **Logic**: 19 19 + 1. It checks if the `.session` file exists. If not, it returns `null`. 20 20 + 2. It reads the file content, parses it as JSON, and casts it to the `SessionData` type. 21 21 + 3. It performs a basic validation to ensure the essential JWT and DID fields are present. If not, it logs a warning and returns `null`. 22 22 + 4. If the session is loaded and valid, it returns the `SessionData` object. 23 23 + - **Error Handling**: If any part of the process fails (e.g., file read error, JSON parse error), it logs the error and returns `null`, forcing a fresh authentication. 24 24 + 25 25 + ### `saveSession(session: SessionData): void` 26 26 + 27 27 + - **Purpose**: To save the current authentication session to the `.session` file. 28 28 + - **Usage**: This is called from `agent.ts` whenever a new session is created (after a fresh login) or an existing session is successfully refreshed. 29 29 + - **Logic**: 30 30 + 1. It serializes the `session` object into a formatted JSON string. 31 31 + 2. It writes the string to the `.session` file. 32 32 + 3. It sets the file permissions to `0o600` (`-rw-------`) using `chmodSync` to ensure the session file, which contains sensitive tokens, is only readable and writable by the user running the application. 33 33 + 34 34 + ### `clearSession(): void` 35 35 + 36 36 + - **Purpose**: To delete the `.session` file from disk. 37 37 + - **Usage**: This function is exported but does not appear to be actively used in the current application flow. It could be used to implement a "logout" feature. 38 38 + - **Logic**: It checks if the file exists and, if so, deletes it using `unlinkSync`. 39 39 + 40 40 + ## Dependencies 41 41 + 42 42 + - **`node:fs`**: Provides the file system functions for reading, writing, deleting, and changing permissions of the session file. 43 43 + - **`node:path`**: Used to construct the absolute path to the session file. 44 44 + - **`./logger.js`**: For logging session management activities and errors.

+49

docs/common/starterPackThreshold.md

··· 1 1 + # `starterPackThreshold.ts` 2 2 + 3 3 + This module is responsible for checking if an account has created too many starter packs within a specific time window. When a threshold is met, it can trigger various moderation actions on the account, such as applying a label, adding a comment, or reporting the account. This is useful for detecting follow-farming behaviour and coordinated campaign activity. 4 4 + 5 5 + ## Key Functions 6 6 + 7 7 + ### `checkStarterPackThreshold(did: string, starterPackUri: string, timestamp: number): Promise<void>` 8 8 + 9 9 + This is the main function of the module. It's called whenever a starter pack is created, and it checks if the creator has exceeded the configured threshold. 10 10 + 11 11 + **Parameters:** 12 12 + 13 13 + - `did`: The DID of the account that created the starter pack. 14 14 + - `starterPackUri`: The AT URI of the newly created starter pack. 15 15 + - `timestamp`: The timestamp of the creation event. 16 16 + 17 17 + **Logic:** 18 18 + 19 19 + 1. **Load Configurations**: It retrieves the cached `STARTER_PACK_THRESHOLD_CONFIGS`. 20 20 + 2. **Check Allowlist**: For each configuration, it first checks if the account is in the `allowlist`. If so, the check is skipped for that configuration. 21 21 + 3. **Track the Creation**: It records the new starter pack creation for the account in Redis using `trackStarterPackForAccount`. This function stores the URI with its timestamp in a sorted set. 22 22 + 4. **Count Recent Creations**: It then uses `getStarterPackCountInWindow` to count how many starter packs the account has created within the defined rolling window (`window` + `windowUnit`). 23 23 + 5. **Check Threshold**: If the `count` is greater than or equal to the `threshold` defined in the configuration, it proceeds to take action. 24 24 + 6. **Format Comment**: A detailed comment is generated including the threshold count, window configuration, and the triggering starter pack URI. 25 25 + 7. **Apply Moderation Actions**: 26 26 + - It logs that the threshold has been met. 27 27 + - It increments the `starterPackThresholdMetCounter` metric. 28 28 + - Based on the booleans `toLabel` (defaults to true), `reportAcct`, and `commentAcct` in the configuration, it will: 29 29 + - Apply a label to the account (`createAccountLabel`). 30 30 + - Report the account (`createAccountReport`). 31 31 + - Add a comment to the account's moderation record (`createAccountComment`). 32 32 + - It also increments the `starterPackLabelsThresholdAppliedCounter` for each action taken. 33 33 + 34 34 + ### `loadStarterPackThresholdConfigs(): StarterPackThresholdConfig[]` 35 35 + 36 36 + This function returns the cached `STARTER_PACK_THRESHOLD_CONFIGS`. The configurations are loaded and validated once at module initialization to avoid re-reading and re-validating the configuration file on every call. 37 37 + 38 38 + ## Supporting Functions 39 39 + 40 40 + - `validateAndLoadConfigs(): StarterPackThresholdConfig[]`: This function is called once when the module is loaded. It iterates through `STARTER_PACK_THRESHOLD_CONFIGS`, validates that each configuration has the required properties (`threshold > 0`, `window > 0`), and then returns the valid configurations. 41 41 + 42 42 + ## Dependencies 43 43 + 44 44 + - **`../../rules/starterPackThreshold.js`**: Contains the `STARTER_PACK_THRESHOLD_CONFIGS` array, which defines the rules for when to take action on an account. 45 45 + - **`./accountModeration.js`**: Provides the functions (`createAccountLabel`, `createAccountReport`, `createAccountComment`) to perform moderation actions on an account. 46 46 + - **`./logger.js`**: Used for logging information, warnings, and errors. 47 47 + - **`./metrics.js`**: Provides Prometheus counters for monitoring the behavior of this module. 48 48 + - **`./redis.js`**: Provides the functions (`trackStarterPackForAccount`, `getStarterPackCountInWindow`) for interacting with Redis to store and retrieve data about starter pack creations. 49 49 + - **`./types.js`**: Defines the `StarterPackThresholdConfig` type.

+67

docs/common/types.md

··· 1 1 + # `types.ts` 2 2 + 3 3 + This module serves as a central repository for common TypeScript interfaces and type definitions used throughout the application. This helps ensure data consistency and provides type safety. 4 4 + 5 5 + ## Core Data Structures 6 6 + 7 7 + - **`Post`**: Represents a simplified post object, containing the essential fields needed for moderation checks. 8 8 + - `did`, `time`, `rkey`, `atURI`, `text`, `cid` 9 9 + 10 10 + - **`Handle`**: Represents a user handle event. 11 11 + - `did`, `time`, `handle` 12 12 + 13 13 + - **`Profile`**: Represents a user profile event. 14 14 + - `did`, `time`, `displayName`, `description` 15 15 + 16 16 + - **`List`**: Represents a list object. (Note: This interface does not appear to be used in the current codebase). 17 17 + - `label`, `rkey` 18 18 + 19 19 + ## Rule Configuration Interfaces 20 20 + 21 21 + - **`Checks`**: A comprehensive interface that defines the structure for a single moderation rule (used for posts, profiles, and handles). 22 22 + - `check`: The primary `RegExp` used to test content. 23 23 + - `whitelist`: An optional `RegExp` to prevent false positives. 24 24 + - `label`: The moderation label to apply. 25 25 + - `comment`: The text to include in the moderation action. 26 26 + - `language`: An optional array of language codes to restrict the rule to. 27 27 + - `ignoredDIDs`: An optional array of DIDs to exempt from the rule. 28 28 + - `starterPacks`: An optional array of starter pack URIs to restrict the rule to members of those packs. 29 29 + - `knownVectors`: An optional array of known vector strings for tracking purposes. 30 30 + - Action booleans: `toLabel`, `reportPost`, `reportAcct`, `commentAcct`, `unlabel`, `trackOnly`. 31 31 + - `duration`: An optional duration in hours for temporary labels. 32 32 + - `description`, `displayName`: Booleans to specify which parts of a profile to check. 33 33 + 34 34 + - **`AccountAgeCheck`**: Defines the structure for a rule in the `accountAge.ts` module. 35 35 + - `monitoredDIDs`, `monitoredPostURIs`: The targets of the monitoring. 36 36 + - `anchorDate`, `maxAgeDays`: The time window for checking the account's creation date. 37 37 + - `label`, `comment`: The action to take if the check passes. 38 38 + - `expires`: An optional date after which the rule is no longer active. 39 39 + 40 40 + - **`WindowUnit`**: A type alias representing the unit for rolling time windows. Valid values are `"minutes"`, `"hours"`, or `"days"`. 41 41 + 42 42 + - **`AccountThresholdConfig`**: Defines the structure for a rule in the `accountThreshold.ts` module. 43 43 + - `labels`: The post label(s) that contribute to the threshold (can be a single string or array for OR matching). 44 44 + - `threshold`: The number of labels required to trigger the action. 45 45 + - `window`: The rolling window duration (number). 46 46 + - `windowUnit`: The unit for the rolling window (`WindowUnit`). 47 47 + - `accountLabel`, `accountComment`: The label and comment for the resulting account action. 48 48 + - Action booleans: `reportAcct`, `commentAcct`, `toLabel` (optional, defaults to true). 49 49 + 50 50 + - **`StarterPackThresholdConfig`**: Defines the structure for a rule in the `starterPackThreshold.ts` module. 51 51 + - `threshold`: The number of starter packs required to trigger the action. 52 52 + - `window`: The rolling window duration (number). 53 53 + - `windowUnit`: The unit for the rolling window (`WindowUnit`). 54 54 + - `accountLabel`, `accountComment`: The label and comment for the resulting account action. 55 55 + - `toLabel`: Optional boolean to apply label (defaults to true). 56 56 + - `reportAcct`: Optional boolean to report the account. 57 57 + - `commentAcct`: Optional boolean to comment on the account. 58 58 + - `allowlist`: Optional array of DIDs to exempt from this check. 59 59 + 60 60 + ## Re-exported Lexicon Types 61 61 + 62 62 + - For convenience, several facet-related types are re-exported directly from the `@atproto/ozone` library's generated lexicons. This avoids the need for other modules to have complex import paths. 63 63 + - `Facet` 64 64 + - `FacetIndex` 65 65 + - `FacetMention` 66 66 + - `LinkFeature` 67 67 + - `FacetTag`

+1 -1

package.json

··· 1 1 { 2 2 "name": "skywatch-automod", 3 3 - "version": "2.0.2", 3 3 + "version": "2.1.0", 4 4 "type": "module", 5 5 "scripts": { 6 6 "start": "npx tsx src/main.ts",

+33 -7

rules/accountAge.ts

··· 3 3 /** 4 4 * Account age monitoring configurations 5 5 * 6 6 - * This file contains example values. Copy to accountAge.ts and configure with your checks. 6 6 + * Labels new accounts that interact with monitored DIDs or posts. 7 7 + * Useful for protecting high-profile accounts from coordinated harassment. 8 8 + * Configure your checks below. 7 9 */ 8 10 export const ACCOUNT_AGE_CHECKS: AccountAgeCheck[] = [ 9 9 - // Example configuration: 11 11 + // Example - monitor replies to specific accounts: 10 12 // { 11 11 - // monitoredDIDs: ["did:plc:example123"], 12 12 - // anchorDate: "2025-01-15", 13 13 - // maxAgeDays: 7, 14 14 - // label: "new-account", 15 15 - // comment: "Account created within monitored window", 13 13 + // monitoredDIDs: ["did:plc:example123", "did:plc:example456"], 14 14 + // anchorDate: "2025-01-15", // Only check accounts created after this date 15 15 + // maxAgeDays: 7, // Flag accounts younger than 7 days 16 16 + // label: "new-account-reply", 17 17 + // comment: "New account replying to monitored user", 18 18 + // expires: "2025-02-15", // Stop checking after this date 19 19 + // }, 20 20 + 21 21 + // Example - monitor replies/quotes to specific posts: 22 22 + // { 23 23 + // monitoredPostURIs: [ 24 24 + // "at://did:plc:xyz/app.bsky.feed.post/abc123", 25 25 + // "at://did:plc:xyz/app.bsky.feed.post/def456", 26 26 + // ], 27 27 + // anchorDate: "2025-01-20", 28 28 + // maxAgeDays: 3, 29 29 + // label: "new-account-quote", 30 30 + // comment: "New account quoting monitored post", 31 31 + // }, 32 32 + 33 33 + // Example - combine both DID and post monitoring: 34 34 + // { 35 35 + // monitoredDIDs: ["did:plc:high-profile"], 36 36 + // monitoredPostURIs: ["at://did:plc:high-profile/app.bsky.feed.post/viral"], 37 37 + // anchorDate: "2025-01-01", 38 38 + // maxAgeDays: 14, 39 39 + // label: "new-account-interaction", 40 40 + // comment: "New account interacting with high-profile content", 41 41 + // expires: "2025-03-01", 16 42 // }, 17 43 ];

+2 -1

rules/accountThreshold.ts

··· 12 12 // threshold: 3, 13 13 // accountLabel: "repeat-offender", 14 14 // accountComment: "Account exceeded threshold", 15 15 - // windowDays: 7, 15 15 + // window: 5, 16 16 + // windowUnit: "hours", 16 17 // reportAcct: false, 17 18 // commentAcct: false, 18 19 // toLabel: true,

+22 -3

rules/constants.ts

··· 1 1 /** 2 2 * Global allowlist for accounts that should bypass all checks 3 3 * 4 4 - * This file contains example values. Copy to constants.ts and configure with your DIDs. 4 4 + * Add DIDs here to exempt them from all moderation checks. 5 5 */ 6 6 export const GLOBAL_ALLOW: string[] = [ 7 7 - // Example: "did:plc:example123", 7 7 + // Example: "did:plc:trusted-account", 8 8 ]; 9 9 10 10 - export const LINK_SHORTENER = new RegExp("", "i"); 10 10 + /** 11 11 + * URL shortener detection pattern 12 12 + * 13 13 + * Matched URLs are resolved to their final destination before checking. 14 14 + * Add domains for URL shorteners you want to expand. 15 15 + */ 16 16 + export const LINK_SHORTENER = new RegExp( 17 17 + [ 18 18 + "bit\\.ly", 19 19 + "tinyurl\\.com", 20 20 + "t\\.co", 21 21 + "goo\\.gl", 22 22 + "ow\\.ly", 23 23 + "is\\.gd", 24 24 + "buff\\.ly", 25 25 + "rebrand\\.ly", 26 26 + "short\\.io", 27 27 + ].join("|"), 28 28 + "i", 29 29 + );

+54 -1

rules/developing_checks.md

··· 105 105 threshold: 3, 106 106 accountLabel: "repeat-offender", 107 107 accountComment: "Account exceeded spam threshold", 108 108 - windowDays: 7, 108 108 + window: 7, 109 109 + windowUnit: "days", // Options: "minutes", "hours", "days" 109 110 reportAcct: true, 110 111 commentAcct: false, 111 112 toLabel: true, ··· 113 114 ]; 114 115 ``` 115 116 117 117 + ### Starter Pack Threshold Checks 118 118 + 119 119 + File: `rules/starterPackThreshold.ts` 120 120 + 121 121 + Applies account-level labels when an account creates too many starter packs within a time window. Useful for detecting follow-farming and coordinated campaign behaviour. 122 122 + 123 123 + ```typescript 124 124 + import type { StarterPackThresholdConfig } from "../src/types.js"; 125 125 + 126 126 + export const STARTER_PACK_THRESHOLD_CONFIGS: StarterPackThresholdConfig[] = [ 127 127 + { 128 128 + threshold: 10, // Account action triggered after 10 starter packs 129 129 + window: 7, // Within this duration 130 130 + windowUnit: "days", // Options: "minutes", "hours", "days" 131 131 + accountLabel: "follow-farming", 132 132 + accountComment: "Account created multiple starter packs in short period", 133 133 + toLabel: true, // Whether to apply the label (default: true) 134 134 + reportAcct: true, // Whether to report the account 135 135 + commentAcct: false, // Whether to comment on the account 136 136 + allowlist: [], // DIDs to exempt from this check 137 137 + }, 138 138 + ]; 139 139 + ``` 140 140 + 116 141 ## Check Configuration Fields 117 142 118 143 ### Basic Fields (Required) ··· 135 160 - `ignoredDIDs` - DIDs to skip checking (string[]) 136 161 - `starterPacks` - Filter by starter pack membership (string[]) 137 162 - `knownVectors` - Known attack vectors for tracking (string[]) 163 163 + - `trackOnly` - Track without applying label (boolean) 164 164 + - `unlabel` - Remove existing label if content no longer matches (boolean) 165 165 + 166 166 + ### Threshold Configuration Fields 167 167 + 168 168 + #### Account Threshold 169 169 + 170 170 + - `labels` - Single label or array of labels to aggregate (string | string[]) 171 171 + - `threshold` - Number of labeled posts required to trigger account action (number) 172 172 + - `window` - Rolling window duration (number) 173 173 + - `windowUnit` - Unit for the rolling window: "minutes", "hours", or "days" (WindowUnit) 174 174 + - `accountLabel` - Label to apply to the account (string) 175 175 + - `accountComment` - Comment for the account action (string) 176 176 + - `toLabel` - Whether to apply the label, defaults to true (boolean) 177 177 + - `reportAcct` - Whether to report the account (boolean) 178 178 + - `commentAcct` - Whether to comment on the account (boolean) 179 179 + 180 180 + #### Starter Pack Threshold 181 181 + 182 182 + - `threshold` - Number of starter packs required to trigger account action (number) 183 183 + - `window` - Rolling window duration (number) 184 184 + - `windowUnit` - Unit for the rolling window: "minutes", "hours", or "days" (WindowUnit) 185 185 + - `accountLabel` - Label to apply to the account (string) 186 186 + - `accountComment` - Comment for the account action (string) 187 187 + - `toLabel` - Whether to apply the label, defaults to true (boolean) 188 188 + - `reportAcct` - Whether to report the account (boolean) 189 189 + - `commentAcct` - Whether to comment on the account (boolean) 190 190 + - `allowlist` - DIDs to exempt from this check (string[]) 138 191 139 192 ## Examples 140 193

+20 -6

rules/handles.ts

··· 3 3 /** 4 4 * Handle-based moderation checks 5 5 * 6 6 - * This file contains example values. Copy to handles.ts and configure with your checks. 6 6 + * Monitors user handles (usernames) for pattern matches. 7 7 + * Configure your checks below. 7 8 */ 8 9 export const HANDLE_CHECKS: Checks[] = [ 9 9 - // Example check: 10 10 + // Basic example - flag potential impersonation: 10 11 // { 11 11 - // label: "example-label", 12 12 - // comment: "Example check found in handle", 13 13 - // reportAcct: false, 12 12 + // label: "impersonation", 13 13 + // comment: "Potential impersonation detected in handle", 14 14 + // reportAcct: true, 15 15 + // commentAcct: false, 16 16 + // toLabel: false, 17 17 + // check: new RegExp("official.*support", "i"), 18 18 + // }, 19 19 + 20 20 + // Advanced example with optional fields: 21 21 + // { 22 22 + // label: "suspicious-handle", 23 23 + // comment: "Handle matches known spam pattern", 24 24 + // reportAcct: true, 14 25 // commentAcct: false, 15 26 // toLabel: true, 16 16 - // check: new RegExp("example-pattern", "i"), 27 27 + // unlabel: true, // Remove label if handle changes 28 28 + // check: new RegExp("crypto.*airdrop", "i"), 29 29 + // whitelist: new RegExp("cryptography", "i"), // Don't match legitimate use 30 30 + // ignoredDIDs: ["did:plc:verified123"], 17 31 // }, 18 32 ];

+25 -5

rules/posts.ts

··· 3 3 /** 4 4 * Post content moderation checks 5 5 * 6 6 - * This file contains example values. Copy to posts.ts and configure with your checks. 6 6 + * Monitors post text and embedded URLs for pattern matches. 7 7 + * Configure your checks below. 7 8 */ 8 9 export const POST_CHECKS: Checks[] = [ 9 9 - // Example check: 10 10 + // Basic example - label posts matching a pattern: 10 11 // { 11 11 - // label: "example-label", 12 12 - // comment: "Example content found in post", 12 12 + // label: "spam", 13 13 + // comment: "Spam content detected in post", 13 14 // reportAcct: false, 14 15 // commentAcct: false, 15 16 // toLabel: true, 16 16 - // check: new RegExp("example-pattern", "i"), 17 17 + // check: new RegExp("buy.*followers", "i"), 18 18 + // }, 19 19 + 20 20 + // Advanced example - all optional fields: 21 21 + // { 22 22 + // label: "scam-link", 23 23 + // comment: "Suspicious link detected", 24 24 + // language: ["eng", "spa"], // Only check posts in these languages 25 25 + // reportAcct: true, // Create account report 26 26 + // reportPost: true, // Create post report 27 27 + // commentAcct: false, // Add comment to account record 28 28 + // toLabel: true, // Apply the label 29 29 + // trackOnly: false, // If true, track but don't take action 30 30 + // unlabel: false, // If true, remove label when no longer matching 31 31 + // duration: 24, // Label expires after 24 hours 32 32 + // check: new RegExp("crypto.*giveaway", "i"), 33 33 + // whitelist: new RegExp("legitimate-site\\.com", "i"), // Skip if this matches 34 34 + // ignoredDIDs: ["did:plc:trusted123"], // Skip these accounts 35 35 + // starterPacks: ["at://did:plc:xyz/app.bsky.graph.starterpack/abc"], // Only check members 36 36 + // knownVectors: ["telegram-scam", "discord-spam"], // Tracking tags 17 37 // }, 18 38 ];

+23 -7

rules/profiles.ts

··· 3 3 /** 4 4 * Profile-based moderation checks 5 5 * 6 6 - * This file contains example values. Copy to profiles.ts and configure with your checks. 6 6 + * Monitors profile display names and descriptions for pattern matches. 7 7 + * Configure your checks below. 7 8 */ 8 9 export const PROFILE_CHECKS: Checks[] = [ 9 9 - // Example check: 10 10 + // Basic example - check both displayName and description: 10 11 // { 11 11 - // label: "example-label", 12 12 - // comment: "Example content found in profile", 13 13 - // description: true, 14 14 - // displayName: true, 12 12 + // label: "spam-profile", 13 13 + // comment: "Spam content in profile", 14 14 + // displayName: true, // Check display name 15 15 + // description: true, // Check description 15 16 // reportAcct: false, 16 17 // commentAcct: false, 17 18 // toLabel: true, 18 18 - // check: new RegExp("example-pattern", "i"), 19 19 + // check: new RegExp("follow.*back.*guaranteed", "i"), 20 20 + // }, 21 21 + 22 22 + // Advanced example - displayName only with unlabel: 23 23 + // { 24 24 + // label: "impersonation-profile", 25 25 + // comment: "Profile impersonating official account", 26 26 + // displayName: true, 27 27 + // description: false, // Only check display name 28 28 + // reportAcct: true, 29 29 + // commentAcct: false, 30 30 + // toLabel: true, 31 31 + // unlabel: true, // Remove label if profile changes 32 32 + // check: new RegExp("official.*bluesky.*team", "i"), 33 33 + // whitelist: new RegExp("parody|fan", "i"), 34 34 + // ignoredDIDs: ["did:plc:actual-team-member"], 19 35 // }, 20 36 ];

+35

rules/starterPackThreshold.ts

··· 1 1 + import type { StarterPackThresholdConfig } from "../src/types.js"; 2 2 + 3 3 + /** 4 4 + * Starter pack threshold configurations 5 5 + * 6 6 + * Labels accounts that create too many starter packs within a time window. 7 7 + * Useful for detecting follow-farming and coordinated campaign behaviour. 8 8 + * Configure your checks below. 9 9 + */ 10 10 + export const STARTER_PACK_THRESHOLD_CONFIGS: StarterPackThresholdConfig[] = [ 11 11 + // Example - detect follow-farming: 12 12 + // { 13 13 + // threshold: 10, // Trigger after 10 starter packs 14 14 + // window: 7, // Within this duration 15 15 + // windowUnit: "days", // Options: "minutes", "hours", "days" 16 16 + // accountLabel: "follow-farming", 17 17 + // accountComment: "Account created multiple starter packs in short period", 18 18 + // toLabel: true, // Apply the label (default: true) 19 19 + // reportAcct: true, // Create account report 20 20 + // commentAcct: false, // Add comment to account record 21 21 + // allowlist: ["did:plc:trusted123"], // DIDs to exempt from this check 22 22 + // }, 23 23 + 24 24 + // Example - stricter threshold for rapid creation: 25 25 + // { 26 26 + // threshold: 5, 27 27 + // window: 1, 28 28 + // windowUnit: "hours", 29 29 + // accountLabel: "spam-starterpack", 30 30 + // accountComment: "Rapid starter pack creation detected", 31 31 + // toLabel: false, 32 32 + // reportAcct: true, 33 33 + // commentAcct: true, 34 34 + // }, 35 35 + ];

+116 -2

src/accountModeration.ts

··· 2 2 import { MOD_DID } from "./config.js"; 3 3 import { limit } from "./limits.js"; 4 4 import { logger } from "./logger.js"; 5 5 - import { labelsAppliedCounter, labelsCachedCounter } from "./metrics.js"; 6 6 - import { tryClaimAccountComment, tryClaimAccountLabel } from "./redis.js"; 5 5 + import { 6 6 + labelsAppliedCounter, 7 7 + labelsCachedCounter, 8 8 + unlabelsRemovedCounter, 9 9 + } from "./metrics.js"; 10 10 + import { 11 11 + deleteAccountLabelClaim, 12 12 + tryClaimAccountComment, 13 13 + tryClaimAccountLabel, 14 14 + } from "./redis.js"; 7 15 8 16 const doesLabelExist = ( 9 17 labels: { val: string }[] | undefined, ··· 73 81 createdAt: new Date().toISOString(), 74 82 modTool: { 75 83 name: "skywatch/skywatch-automod", 84 84 + meta: { 85 85 + time: new Date().toISOString(), 86 86 + externalUrl: `https://pdsls.dev/at://${did}`, 87 87 + }, 76 88 }, 77 89 }, 78 90 { ··· 89 101 { process: "MODERATION", error: e }, 90 102 "Failed to create account label", 91 103 ); 104 104 + throw e; 92 105 } 93 106 }); 94 107 }; ··· 129 142 createdAt: new Date().toISOString(), 130 143 modTool: { 131 144 name: "skywatch/skywatch-automod", 145 145 + meta: { 146 146 + time: new Date().toISOString(), 147 147 + externalUrl: `https://pdsls.dev/at://${did}`, 148 148 + }, 132 149 }, 133 150 }, 134 151 { ··· 145 162 { process: "MODERATION", error: e }, 146 163 "Failed to create account comment", 147 164 ); 165 165 + throw e; 148 166 } 149 167 }); 150 168 }; ··· 170 188 createdAt: new Date().toISOString(), 171 189 modTool: { 172 190 name: "skywatch/skywatch-automod", 191 191 + meta: { 192 192 + time: new Date().toISOString(), 193 193 + externalUrl: `https://pdsls.dev/at://${did}`, 194 194 + }, 173 195 }, 174 196 }, 175 197 { ··· 186 208 { process: "MODERATION", error: e }, 187 209 "Failed to create account report", 188 210 ); 211 211 + throw e; 212 212 + } 213 213 + }); 214 214 + }; 215 215 + 216 216 + export const negateAccountLabel = async ( 217 217 + did: string, 218 218 + label: string, 219 219 + comment: string, 220 220 + ) => { 221 221 + await isLoggedIn; 222 222 + 223 223 + const hasLabel = await checkAccountLabels(did, label); 224 224 + if (!hasLabel) { 225 225 + logger.debug( 226 226 + { process: "MODERATION", did, label }, 227 227 + "Account does not have label, skipping", 228 228 + ); 229 229 + return; 230 230 + } 231 231 + 232 232 + logger.info({ process: "MODERATION", did, label }, "Unlabeling account"); 233 233 + unlabelsRemovedCounter.inc({ label_type: label, target_type: "account" }); 234 234 + 235 235 + await limit(async () => { 236 236 + try { 237 237 + await agent.tools.ozone.moderation.emitEvent( 238 238 + { 239 239 + event: { 240 240 + $type: "tools.ozone.moderation.defs#modEventLabel", 241 241 + comment, 242 242 + createLabelVals: [], 243 243 + negateLabelVals: [label], 244 244 + }, 245 245 + // specify the labeled post by strongRef 246 246 + subject: { 247 247 + $type: "com.atproto.admin.defs#repoRef", 248 248 + did, 249 249 + }, 250 250 + // put in the rest of the metadata 251 251 + createdBy: agent.did ?? "", 252 252 + createdAt: new Date().toISOString(), 253 253 + modTool: { 254 254 + name: "skywatch/skywatch-automod", 255 255 + meta: { 256 256 + time: new Date().toISOString(), 257 257 + externalUrl: `https://pdsls.dev/at://${did}`, 258 258 + }, 259 259 + }, 260 260 + }, 261 261 + { 262 262 + encoding: "application/json", 263 263 + headers: { 264 264 + "atproto-proxy": `${MOD_DID}#atproto_labeler`, 265 265 + "atproto-accept-labelers": 266 266 + "did:plc:ar7c4by46qjdydhdevvrndac;redact", 267 267 + }, 268 268 + }, 269 269 + ); 270 270 + await deleteAccountLabelClaim(did, label); 271 271 + } catch (e) { 272 272 + logger.error( 273 273 + { process: "MODERATION", error: e }, 274 274 + "Failed to negate account label", 275 275 + ); 276 276 + throw e; 189 277 } 190 278 }); 191 279 }; ··· 218 306 } 219 307 }); 220 308 }; 309 309 + 310 310 + export const getAllAccountLabels = async (did: string): Promise<string[]> => { 311 311 + await isLoggedIn; 312 312 + return await limit(async () => { 313 313 + try { 314 314 + const response = await agent.tools.ozone.moderation.getRepo( 315 315 + { did }, 316 316 + { 317 317 + headers: { 318 318 + "atproto-proxy": `${MOD_DID}#atproto_labeler`, 319 319 + "atproto-accept-labelers": 320 320 + "did:plc:ar7c4by46qjdydhdevvrndac;redact", 321 321 + }, 322 322 + }, 323 323 + ); 324 324 + 325 325 + return (response.data.labels ?? []).map((label) => label.val); 326 326 + } catch (e) { 327 327 + logger.error( 328 328 + { process: "MODERATION", did, error: e }, 329 329 + "Failed to get account labels", 330 330 + ); 331 331 + return []; 332 332 + } 333 333 + }); 334 334 + };

+14 -12

src/accountThreshold.ts

··· 41 41 `Invalid account threshold config: threshold must be positive`, 42 42 ); 43 43 } 44 44 - if (config.windowDays <= 0) { 44 44 + if (config.window <= 0) { 45 45 throw new Error( 46 46 - `Invalid account threshold config: windowDays must be positive`, 46 46 + `Invalid account threshold config: window must be positive`, 47 47 ); 48 48 } 49 49 } ··· 65 65 66 66 export async function checkAccountThreshold( 67 67 did: string, 68 68 + uri: string, 68 69 postLabel: string, 69 70 timestamp: number, 70 71 ): Promise<void> { ··· 93 94 did, 94 95 postLabel, 95 96 timestamp, 96 96 - config.windowDays, 97 97 + config.window, 98 98 + config.windowUnit, 97 99 ); 98 100 99 101 const count = await getPostLabelCountInWindow( 100 102 did, 101 103 labels, 102 102 - config.windowDays, 104 104 + config.window, 105 105 + config.windowUnit, 103 106 timestamp, 104 107 ); 105 108 ··· 110 113 labels, 111 114 count, 112 115 threshold: config.threshold, 113 113 - windowDays: config.windowDays, 116 116 + window: config.window, 117 117 + windowUnit: config.windowUnit, 114 118 }, 115 119 "Checked account threshold", 116 120 ); ··· 132 136 133 137 const shouldLabel = config.toLabel !== false; 134 138 139 139 + const formattedComment = `${config.accountComment}\n\nThreshold: ${count.toString()}/${config.threshold.toString()} in ${config.window.toString()} ${config.windowUnit}\n\nPost: ${uri}\n\nPost Label: ${postLabel}`; 140 140 + 135 141 if (shouldLabel) { 136 136 - await createAccountLabel( 137 137 - did, 138 138 - config.accountLabel, 139 139 - config.accountComment, 140 140 - ); 142 142 + await createAccountLabel(did, config.accountLabel, formattedComment); 141 143 accountLabelsThresholdAppliedCounter.inc({ 142 144 account_label: config.accountLabel, 143 145 action: "label", ··· 145 147 } 146 148 147 149 if (config.reportAcct) { 148 148 - await createAccountReport(did, config.accountComment); 150 150 + await createAccountReport(did, formattedComment); 149 151 accountLabelsThresholdAppliedCounter.inc({ 150 152 account_label: config.accountLabel, 151 153 action: "report", ··· 154 156 155 157 if (config.commentAcct) { 156 158 const atURI = `threshold-comment:${config.accountLabel}:${timestamp.toString()}`; 157 157 - await createAccountComment(did, config.accountComment, atURI); 159 159 + await createAccountComment(did, formattedComment, atURI); 158 160 accountLabelsThresholdAppliedCounter.inc({ 159 161 account_label: config.accountLabel, 160 162 action: "comment",

+67 -4

src/agent.ts

··· 99 99 } 100 100 } 101 101 102 102 + const MAX_LOGIN_RETRIES = 3; 103 103 + const RETRY_DELAY_MS = 2000; 104 104 + 105 105 + let loginPromise: Promise<void> | null = null; 106 106 + 107 107 + async function sleep(ms: number): Promise<void> { 108 108 + return new Promise((resolve) => setTimeout(resolve, ms)); 109 109 + } 110 110 + 102 111 async function authenticate(): Promise<boolean> { 103 112 const savedSession = loadSession(); 104 113 ··· 121 130 return performLogin(); 122 131 } 123 132 124 124 - export const login = authenticate; 125 125 - export const isLoggedIn = authenticate() 126 126 - .then((success) => success) 127 127 - .catch(() => false); 133 133 + async function authenticateWithRetry(): Promise<void> { 134 134 + // Reuse existing login attempt if one is in progress 135 135 + if (loginPromise) { 136 136 + return loginPromise; 137 137 + } 138 138 + 139 139 + loginPromise = (async () => { 140 140 + for (let attempt = 1; attempt <= MAX_LOGIN_RETRIES; attempt++) { 141 141 + logger.info( 142 142 + { attempt, maxRetries: MAX_LOGIN_RETRIES }, 143 143 + "Attempting login", 144 144 + ); 145 145 + 146 146 + const success = await authenticate(); 147 147 + 148 148 + if (success) { 149 149 + logger.info("Authentication successful"); 150 150 + return; 151 151 + } 152 152 + 153 153 + if (attempt < MAX_LOGIN_RETRIES) { 154 154 + logger.warn( 155 155 + { attempt, maxRetries: MAX_LOGIN_RETRIES, retryInMs: RETRY_DELAY_MS }, 156 156 + "Login failed, retrying", 157 157 + ); 158 158 + await sleep(RETRY_DELAY_MS); 159 159 + } 160 160 + } 161 161 + 162 162 + logger.error( 163 163 + { maxRetries: MAX_LOGIN_RETRIES }, 164 164 + "All login attempts failed, aborting", 165 165 + ); 166 166 + process.exit(1); 167 167 + })(); 168 168 + 169 169 + return loginPromise; 170 170 + } 171 171 + 172 172 + export const login = authenticateWithRetry; 173 173 + 174 174 + // Lazy getter for isLoggedIn - authentication only starts when first accessed 175 175 + let _isLoggedIn: Promise<boolean> | null = null; 176 176 + 177 177 + export function getIsLoggedIn(): Promise<boolean> { 178 178 + if (!_isLoggedIn) { 179 179 + _isLoggedIn = authenticateWithRetry().then(() => true); 180 180 + } 181 181 + return _isLoggedIn; 182 182 + } 183 183 + 184 184 + // For backward compatibility - callers can still use `await isLoggedIn` 185 185 + // but authentication is now lazy instead of eager 186 186 + export const isLoggedIn = { 187 187 + then<T>(onFulfilled: (value: boolean) => T | PromiseLike<T>): Promise<T> { 188 188 + return getIsLoggedIn().then(onFulfilled); 189 189 + }, 190 190 + };

+1

src/config.ts

··· 16 16 "app.bsky.feed.post", 17 17 "app.bsky.actor.defs", 18 18 "app.bsky.actor.profile", 19 19 + "app.bsky.graph.starterpack", 19 20 ]; 20 21 export const CURSOR_UPDATE_INTERVAL = process.env.CURSOR_UPDATE_INTERVAL 21 22 ? Number(process.env.CURSOR_UPDATE_INTERVAL)

+18 -18

src/main.ts

··· 5 5 IdentityEvent, 6 6 } from "@skyware/jetstream"; 7 7 import { Jetstream } from "@skyware/jetstream"; 8 8 + import { login } from "./agent.js"; 8 9 import { 9 10 CURSOR_UPDATE_INTERVAL, 10 11 FIREHOSE_URL, ··· 18 19 import { checkFacetSpam } from "./rules/facets/facets.js"; 19 20 import { checkHandle } from "./rules/handles/checkHandles.js"; 20 21 import { checkPosts } from "./rules/posts/checkPosts.js"; 21 21 - import { 22 22 - checkDescription, 23 23 - checkDisplayName, 24 24 - } from "./rules/profiles/checkProfiles.js"; 22 22 + import { checkProfile } from "./rules/profiles/checkProfiles.js"; 23 23 + import { checkStarterPackThreshold } from "./starterPackThreshold.js"; 25 24 import type { Post } from "./types.js"; 26 25 27 26 let cursor = 0; ··· 281 280 async (event: CommitUpdateEvent<"app.bsky.actor.profile">) => { 282 281 try { 283 282 if (event.commit.record.displayName || event.commit.record.description) { 284 284 - void checkDescription( 285 285 - event.did, 286 286 - event.time_us, 287 287 - event.commit.record.displayName as string, 288 288 - event.commit.record.description as string, 289 289 - ); 290 290 - void checkDisplayName( 283 283 + void checkProfile( 291 284 event.did, 292 285 event.time_us, 293 286 event.commit.record.displayName as string, ··· 308 301 async (event: CommitCreateEvent<"app.bsky.actor.profile">) => { 309 302 try { 310 303 if (event.commit.record.displayName || event.commit.record.description) { 311 311 - void checkDescription( 312 312 - event.did, 313 313 - event.time_us, 314 314 - event.commit.record.displayName as string, 315 315 - event.commit.record.description as string, 316 316 - ); 317 317 - void checkDisplayName( 304 304 + void checkProfile( 318 305 event.did, 319 306 event.time_us, 320 307 event.commit.record.displayName as string, ··· 339 326 }, 340 327 ); 341 328 329 329 + // Check for starter pack creation 330 330 + jetstream.onCreate( 331 331 + "app.bsky.graph.starterpack", 332 332 + (event: CommitCreateEvent<"app.bsky.graph.starterpack">) => { 333 333 + const starterPackUri = `at://${event.did}/app.bsky.graph.starterpack/${event.commit.rkey}`; 334 334 + void checkStarterPackThreshold(event.did, starterPackUri, event.time_us); 335 335 + }, 336 336 + ); 337 337 + 342 338 const metricsServer = startMetricsServer(METRICS_PORT); 343 339 344 340 logger.info({ process: "MAIN" }, "Connecting to Redis"); 345 341 await connectRedis(); 342 342 + 343 343 + logger.info({ process: "MAIN" }, "Authenticating with Bluesky"); 344 344 + await login(); 345 345 + logger.info({ process: "MAIN" }, "Authentication complete, starting Jetstream"); 346 346 347 347 jetstream.start(); 348 348

+34

src/metrics.ts

··· 20 20 registers: [register], 21 21 }); 22 22 23 23 + export const unlabelsRemovedCounter: Counter = new Counter({ 24 24 + name: "skywatch_labels_removed_total", 25 25 + help: "Total number of labels removed due to criteria no longer matching", 26 26 + labelNames: ["label_type", "target_type"], 27 27 + registers: [register], 28 28 + }); 29 29 + 23 30 export const accountLabelsThresholdAppliedCounter = new Counter({ 24 31 name: "skywatch_account_labels_threshold_applied_total", 25 32 help: "Total number of account actions applied due to threshold", ··· 38 45 name: "skywatch_account_threshold_met_total", 39 46 help: "Total number of times account thresholds were met", 40 47 labelNames: ["account_label"], 48 48 + registers: [register], 49 49 + }); 50 50 + 51 51 + export const starterPackThresholdChecksCounter = new Counter({ 52 52 + name: "skywatch_starter_pack_threshold_checks_total", 53 53 + help: "Total number of starter pack threshold checks performed", 54 54 + registers: [register], 55 55 + }); 56 56 + 57 57 + export const starterPackThresholdMetCounter = new Counter({ 58 58 + name: "skywatch_starter_pack_threshold_met_total", 59 59 + help: "Total number of times starter pack thresholds were met", 60 60 + labelNames: ["account_label"], 61 61 + registers: [register], 62 62 + }); 63 63 + 64 64 + export const starterPackLabelsThresholdAppliedCounter = new Counter({ 65 65 + name: "skywatch_starter_pack_labels_threshold_applied_total", 66 66 + help: "Total number of account actions applied due to starter pack threshold", 67 67 + labelNames: ["account_label", "action"], 68 68 + registers: [register], 69 69 + }); 70 70 + 71 71 + export const moderationActionsFailedCounter = new Counter({ 72 72 + name: "skywatch_moderation_actions_failed_total", 73 73 + help: "Total number of moderation actions that failed", 74 74 + labelNames: ["action", "target_type"], 41 75 registers: [register], 42 76 }); 43 77

+12 -2

src/moderation.ts

··· 93 93 createdAt: new Date().toISOString(), 94 94 modTool: { 95 95 name: "skywatch/skywatch-automod", 96 96 + meta: { 97 97 + time: new Date().toISOString(), 98 98 + externalUrl: `https://pdsls.dev/${uri}`, 99 99 + }, 96 100 }, 97 101 }, 98 102 { ··· 113 117 const { checkAccountThreshold } = await import( 114 118 "./accountThreshold.js" 115 119 ); 116 116 - await checkAccountThreshold(did, label, time); 120 120 + await checkAccountThreshold(did, uri, label, time); 117 121 } catch (error) { 118 122 logger.error( 119 123 { process: "ACCOUNT_THRESHOLD", did, label, error }, ··· 126 130 { process: "MODERATION", error: e }, 127 131 "Failed to create post label", 128 132 ); 133 133 + throw e; 129 134 } 130 135 }); 131 136 }; ··· 156 161 createdAt: new Date().toISOString(), 157 162 modTool: { 158 163 name: "skywatch/skywatch-automod", 164 164 + meta: { 165 165 + time: new Date().toISOString(), 166 166 + externalUrl: `https://pdsls.dev/${uri}`, 167 167 + }, 159 168 }, 160 169 }, 161 170 { ··· 170 179 } catch (e) { 171 180 logger.error( 172 181 { process: "MODERATION", error: e }, 173 173 - "Failed to create post label", 182 182 + "Failed to create post report", 174 183 ); 184 184 + throw e; 175 185 } 176 186 }); 177 187 };

+122 -13

src/redis.ts

··· 1 1 import { createClient } from "redis"; 2 2 import { REDIS_URL } from "./config.js"; 3 3 import { logger } from "./logger.js"; 4 4 + import type { WindowUnit } from "./types.js"; 4 5 5 6 export const redisClient = createClient({ 6 7 url: REDIS_URL, ··· 88 89 } 89 90 } 90 91 92 92 + export async function deleteAccountLabelClaim( 93 93 + did: string, 94 94 + label: string, 95 95 + ): Promise<void> { 96 96 + try { 97 97 + const key = getAccountLabelCacheKey(did, label); 98 98 + await redisClient.del(key); 99 99 + logger.debug( 100 100 + { did, label }, 101 101 + "Deleted account label claim from Redis cache", 102 102 + ); 103 103 + } catch (err) { 104 104 + logger.warn( 105 105 + { err, did, label }, 106 106 + "Error deleting account label claim from Redis", 107 107 + ); 108 108 + } 109 109 + } 110 110 + 91 111 export async function tryClaimAccountComment( 92 112 did: string, 93 113 atURI: string, ··· 108 128 } 109 129 } 110 130 131 131 + function windowToMicroseconds(window: number, unit: WindowUnit): number { 132 132 + const multipliers: Record<WindowUnit, number> = { 133 133 + minutes: 60 * 1000000, 134 134 + hours: 60 * 60 * 1000000, 135 135 + days: 24 * 60 * 60 * 1000000, 136 136 + }; 137 137 + return window * multipliers[unit]; 138 138 + } 139 139 + 140 140 + function windowToSeconds(window: number, unit: WindowUnit): number { 141 141 + const multipliers: Record<WindowUnit, number> = { 142 142 + minutes: 60, 143 143 + hours: 60 * 60, 144 144 + days: 24 * 60 * 60, 145 145 + }; 146 146 + return window * multipliers[unit]; 147 147 + } 148 148 + 111 149 function getPostLabelTrackingKey( 112 150 did: string, 113 151 label: string, 114 114 - windowDays: number, 152 152 + window: number, 153 153 + unit: WindowUnit, 154 154 + ): string { 155 155 + return `account-post-labels:${did}:${label}:${window.toString()}${unit}`; 156 156 + } 157 157 + 158 158 + function getStarterPackTrackingKey( 159 159 + did: string, 160 160 + window: number, 161 161 + unit: WindowUnit, 115 162 ): string { 116 116 - return `account-post-labels:${did}:${label}:${windowDays.toString()}`; 163 163 + return `starterpack:threshold:${did}:${window.toString()}${unit}`; 164 164 + } 165 165 + 166 166 + export async function trackStarterPackForAccount( 167 167 + did: string, 168 168 + starterPackUri: string, 169 169 + timestamp: number, 170 170 + window: number, 171 171 + windowUnit: WindowUnit, 172 172 + ): Promise<void> { 173 173 + try { 174 174 + const key = getStarterPackTrackingKey(did, window, windowUnit); 175 175 + const windowStartTime = timestamp - windowToMicroseconds(window, windowUnit); 176 176 + 177 177 + await redisClient.zRemRangeByScore(key, "-inf", windowStartTime); 178 178 + 179 179 + await redisClient.zAdd(key, { 180 180 + score: timestamp, 181 181 + value: starterPackUri, 182 182 + }); 183 183 + 184 184 + const ttlSeconds = windowToSeconds(window, windowUnit) + 60 * 60; 185 185 + await redisClient.expire(key, ttlSeconds); 186 186 + 187 187 + logger.debug( 188 188 + { did, starterPackUri, timestamp, window, windowUnit }, 189 189 + "Tracked starter pack for account", 190 190 + ); 191 191 + } catch (err) { 192 192 + logger.error( 193 193 + { err, did, starterPackUri, timestamp, window, windowUnit }, 194 194 + "Error tracking starter pack in Redis", 195 195 + ); 196 196 + throw err; 197 197 + } 198 198 + } 199 199 + 200 200 + export async function getStarterPackCountInWindow( 201 201 + did: string, 202 202 + window: number, 203 203 + windowUnit: WindowUnit, 204 204 + currentTime: number, 205 205 + ): Promise<number> { 206 206 + try { 207 207 + const key = getStarterPackTrackingKey(did, window, windowUnit); 208 208 + const windowStartTime = currentTime - windowToMicroseconds(window, windowUnit); 209 209 + const count = await redisClient.zCount(key, windowStartTime, "+inf"); 210 210 + 211 211 + logger.debug( 212 212 + { did, window, windowUnit, count }, 213 213 + "Retrieved starter pack count in window", 214 214 + ); 215 215 + 216 216 + return count; 217 217 + } catch (err) { 218 218 + logger.error( 219 219 + { err, did, window, windowUnit }, 220 220 + "Error getting starter pack count from Redis", 221 221 + ); 222 222 + throw err; 223 223 + } 117 224 } 118 225 119 226 export async function trackPostLabelForAccount( 120 227 did: string, 121 228 label: string, 122 229 timestamp: number, 123 123 - windowDays: number, 230 230 + window: number, 231 231 + windowUnit: WindowUnit, 124 232 ): Promise<void> { 125 233 try { 126 126 - const key = getPostLabelTrackingKey(did, label, windowDays); 127 127 - const windowStartTime = timestamp - windowDays * 24 * 60 * 60 * 1000000; 234 234 + const key = getPostLabelTrackingKey(did, label, window, windowUnit); 235 235 + const windowStartTime = timestamp - windowToMicroseconds(window, windowUnit); 128 236 129 237 await redisClient.zRemRangeByScore(key, "-inf", windowStartTime); 130 238 ··· 133 241 value: timestamp.toString(), 134 242 }); 135 243 136 136 - const ttlSeconds = (windowDays + 1) * 24 * 60 * 60; 244 244 + const ttlSeconds = windowToSeconds(window, windowUnit) + 60 * 60; 137 245 await redisClient.expire(key, ttlSeconds); 138 246 139 247 logger.debug( 140 140 - { did, label, timestamp, windowDays }, 248 248 + { did, label, timestamp, window, windowUnit }, 141 249 "Tracked post label for account", 142 250 ); 143 251 } catch (err) { 144 252 logger.error( 145 145 - { err, did, label, timestamp, windowDays }, 253 253 + { err, did, label, timestamp, window, windowUnit }, 146 254 "Error tracking post label in Redis", 147 255 ); 148 256 throw err; ··· 152 260 export async function getPostLabelCountInWindow( 153 261 did: string, 154 262 labels: string[], 155 155 - windowDays: number, 263 263 + window: number, 264 264 + windowUnit: WindowUnit, 156 265 currentTime: number, 157 266 ): Promise<number> { 158 267 try { 159 159 - const windowStartTime = currentTime - windowDays * 24 * 60 * 60 * 1000000; 268 268 + const windowStartTime = currentTime - windowToMicroseconds(window, windowUnit); 160 269 let totalCount = 0; 161 270 162 271 for (const label of labels) { 163 163 - const key = getPostLabelTrackingKey(did, label, windowDays); 272 272 + const key = getPostLabelTrackingKey(did, label, window, windowUnit); 164 273 const count = await redisClient.zCount(key, windowStartTime, "+inf"); 165 274 totalCount += count; 166 275 } 167 276 168 277 logger.debug( 169 169 - { did, labels, windowDays, totalCount }, 278 278 + { did, labels, window, windowUnit, totalCount }, 170 279 "Retrieved post label count in window", 171 280 ); 172 281 173 282 return totalCount; 174 283 } catch (err) { 175 284 logger.error( 176 176 - { err, did, labels, windowDays }, 285 285 + { err, did, labels, window, windowUnit }, 177 286 "Error getting post label count from Redis", 178 287 ); 179 288 throw err;

+1 -1

src/rules/account/age.ts

··· 240 240 await createAccountLabel( 241 241 context.actorDid, 242 242 check.label, 243 243 - `${context.time.toString()}: ${check.comment} - Account created within monitored range - Interaction: ${context.atURI}`, 243 243 + `${context.time.toString()}: ${check.comment} \n\nAccount created within monitored range. \n\nInteraction: ${context.atURI}`, 244 244 ); 245 245 246 246 // Only apply one label per interaction

+18 -6

src/rules/account/countStarterPacks.ts

··· 2 2 import { agent, isLoggedIn } from "../../agent.js"; 3 3 import { limit } from "../../limits.js"; 4 4 import { logger } from "../../logger.js"; 5 5 + import { moderationActionsFailedCounter } from "../../metrics.js"; 5 6 6 6 - const ALLOWED_DIDS = ["did:plc:gpunjjgvlyb4racypz3yfiq4"]; 7 7 + const ALLOWED_DIDS = ["did:plc:example"]; 7 8 8 9 export const countStarterPacks = async (did: string, time: number) => { 9 10 await isLoggedIn; ··· 32 33 "Labeling account with excessive starter packs", 33 34 ); 34 35 35 35 - void createAccountLabel( 36 36 - did, 37 37 - "follow-farming", 38 38 - `${time.toString()}: Account has ${starterPacks.toString()} starter packs`, 39 39 - ); 36 36 + try { 37 37 + await createAccountLabel( 38 38 + did, 39 39 + "follow-farming", 40 40 + `${time.toString()}: Account has ${starterPacks.toString()} starter packs`, 41 41 + ); 42 42 + } catch (labelError) { 43 43 + logger.error( 44 44 + { process: "COUNTSTARTERPACKS", did, time, error: labelError }, 45 45 + "Failed to apply follow-farming label", 46 46 + ); 47 47 + moderationActionsFailedCounter.inc({ 48 48 + action: "label", 49 49 + target_type: "account", 50 50 + }); 51 51 + } 40 52 } 41 53 } catch (error) { 42 54 const errorInfo =

+3 -3

src/rules/facets/facets.ts

··· 6 6 export const FACET_SPAM_THRESHOLD = 1; 7 7 8 8 // Label configuration 9 9 - export const FACET_SPAM_LABEL = "suspect-inauthentic"; 9 9 + export const FACET_SPAM_LABEL = "platform-manipulation"; 10 10 export const FACET_SPAM_COMMENT = 11 11 "Abusive facet usage detected (hidden mentions)"; 12 12 13 13 // Allowlist for DIDs with legitimate duplicate facet use cases 14 14 export const FACET_SPAM_ALLOWLIST: string[] = [ 15 15 - // Add DIDs here that should be exempt from facet spam detection 15 15 + "did:plc:ei7hqam5oasdpw5cdihdphcv", 16 16 ]; 17 17 18 18 /** ··· 80 80 await createAccountLabel( 81 81 did, 82 82 FACET_SPAM_LABEL, 83 83 - `${time.toString()}: ${FACET_SPAM_COMMENT} - ${uniqueCount.toString()} unique mentions at position ${position} in ${atURI}`, 83 83 + `${time.toString()}: ${FACET_SPAM_COMMENT} \n\n${uniqueCount.toString()} unique mentions at position ${position}. \n\nPost: ${atURI}`, 84 84 ); 85 85 86 86 // Only label once per post even if multiple positions are suspicious

+2 -2

src/rules/facets/tests/facets.test.ts

··· 251 251 expect(createAccountLabel).toHaveBeenCalledWith( 252 252 TEST_DID, 253 253 FACET_SPAM_LABEL, 254 254 - `${TEST_TIME}: ${FACET_SPAM_COMMENT} - 2 unique mentions at position 0:1 in ${TEST_URI}`, 254 254 + `${TEST_TIME}: ${FACET_SPAM_COMMENT} \n\n2 unique mentions at position 0:1. \n\nPost: ${TEST_URI}`, 255 255 ); 256 256 }); 257 257 ··· 355 355 }); 356 356 357 357 it("should use correct label and comment constants", () => { 358 358 - expect(FACET_SPAM_LABEL).toBe("suspect-inauthentic"); 358 358 + expect(FACET_SPAM_LABEL).toBe("platform-manipulation"); 359 359 expect(FACET_SPAM_COMMENT).toBe( 360 360 "Abusive facet usage detected (hidden mentions)", 361 361 );

+12 -12

src/rules/handles/checkHandles.test.ts

··· 103 103 104 104 expect(createAccountReport).toHaveBeenCalledWith( 105 105 "did:plc:user1", 106 106 - `${time}: Spam detected - spam-account`, 106 106 + `${time}: Spam detected\n\nHandle: spam-account`, 107 107 ); 108 108 }); 109 109 ··· 121 121 122 122 expect(createAccountReport).toHaveBeenCalledWith( 123 123 "did:plc:user1", 124 124 - `${time}: Spam detected - SPAM-ACCOUNT`, 124 124 + `${time}: Spam detected\n\nHandle: SPAM-ACCOUNT`, 125 125 ); 126 126 }); 127 127 }); ··· 139 139 140 140 expect(createAccountComment).toHaveBeenCalledWith( 141 141 "did:plc:user1", 142 142 - `${time}: Scam detected - scam-account`, 142 142 + `${time}: Scam detected\n\nHandle: scam-account`, 143 143 "handle:did:plc:user1:scam-account", 144 144 ); 145 145 }); ··· 159 159 expect(createAccountLabel).toHaveBeenCalledWith( 160 160 "did:plc:normaluser", 161 161 "bot", 162 162 - `${time}: Bot detected - bot-456`, 162 162 + `${time}: Bot detected\n\nHandle: bot-456`, 163 163 ); 164 164 }); 165 165 }); ··· 171 171 172 172 expect(createAccountReport).toHaveBeenCalledWith( 173 173 "did:plc:user1", 174 174 - `${time}: Spam detected - spam-user`, 174 174 + `${time}: Spam detected\n\nHandle: spam-user`, 175 175 ); 176 176 }); 177 177 ··· 181 181 182 182 expect(createAccountComment).toHaveBeenCalledWith( 183 183 "did:plc:user1", 184 184 - `${time}: Scam detected - scam-user`, 184 184 + `${time}: Scam detected\n\nHandle: scam-user`, 185 185 "handle:did:plc:user1:scam-user", 186 186 ); 187 187 }); ··· 193 193 expect(createAccountLabel).toHaveBeenCalledWith( 194 194 "did:plc:user1", 195 195 "bot", 196 196 - `${time}: Bot detected - bot-789`, 196 196 + `${time}: Bot detected\n\nHandle: bot-789`, 197 197 ); 198 198 }); 199 199 ··· 203 203 204 204 expect(createAccountReport).toHaveBeenCalledWith( 205 205 "did:plc:user1", 206 206 - `${time}: Multi-action triggered - dangerous-account`, 206 206 + `${time}: Multi-action triggered\n\nHandle: dangerous-account`, 207 207 ); 208 208 expect(createAccountComment).toHaveBeenCalledWith( 209 209 "did:plc:user1", 210 210 - `${time}: Multi-action triggered - dangerous-account`, 210 210 + `${time}: Multi-action triggered\n\nHandle: dangerous-account`, 211 211 "handle:did:plc:user1:dangerous-account", 212 212 ); 213 213 expect(createAccountLabel).toHaveBeenCalledWith( 214 214 "did:plc:user1", 215 215 "multi-action", 216 216 - `${time}: Multi-action triggered - dangerous-account`, 216 216 + `${time}: Multi-action triggered\n\nHandle: dangerous-account`, 217 217 ); 218 218 }); 219 219 }); ··· 276 276 277 277 expect(createAccountReport).toHaveBeenCalledWith( 278 278 "did:plc:user1", 279 279 - `${time}: Spam detected - ${longHandle}`, 279 279 + `${time}: Spam detected\n\nHandle: ${longHandle}`, 280 280 ); 281 281 }); 282 282 ··· 294 294 295 295 expect(createAccountReport).toHaveBeenCalledWith( 296 296 "did:plc:user1", 297 297 - "1234567890: Spam detected - spam-account", 297 297 + "1234567890: Spam detected\n\nHandle: spam-account", 298 298 ); 299 299 }); 300 300

+5 -10

src/rules/handles/checkHandles.ts

··· 45 45 } 46 46 } 47 47 48 48 + const formattedComment = `${time.toString()}: ${checkList.comment}\n\nHandle: ${handle}`; 49 49 + 48 50 if (checkList.toLabel) { 49 49 - void createAccountLabel( 50 50 - did, 51 51 - checkList.label, 52 52 - `${time.toString()}: ${checkList.comment} - ${handle}`, 53 53 - ); 51 51 + void createAccountLabel(did, checkList.label, formattedComment); 54 52 } 55 53 56 54 if (checkList.reportAcct) { ··· 58 56 { process: "CHECKHANDLE", did, handle, time, label: checkList.label }, 59 57 "Reporting account", 60 58 ); 61 61 - void createAccountReport( 62 62 - did, 63 63 - `${time.toString()}: ${checkList.comment} - ${handle}`, 64 64 - ); 59 59 + void createAccountReport(did, formattedComment); 65 60 } 66 61 67 62 if (checkList.commentAcct) { 68 63 void createAccountComment( 69 64 did, 70 70 - `${time.toString()}: ${checkList.comment} - ${handle}`, 65 65 + formattedComment, 71 66 `handle:${did}:${handle}`, 72 67 ); 73 68 }

+91 -30

src/rules/posts/checkPosts.ts

··· 4 4 createAccountComment, 5 5 createAccountReport, 6 6 } from "../../accountModeration.js"; 7 7 + import { checkAccountThreshold } from "../../accountThreshold.js"; 7 8 import { logger } from "../../logger.js"; 9 9 + import { moderationActionsFailedCounter } from "../../metrics.js"; 8 10 import { createPostLabel, createPostReport } from "../../moderation.js"; 9 9 - import type { Post } from "../../types.js"; 11 11 + import type { ModerationResult, Post } from "../../types.js"; 10 12 import { getFinalUrl } from "../../utils/getFinalUrl.js"; 11 13 import { getLanguage } from "../../utils/getLanguage.js"; 12 14 import { countStarterPacks } from "../account/countStarterPacks.js"; ··· 73 75 const lang = await getLanguage(post[0].text); 74 76 75 77 // iterate through the checks 76 76 - POST_CHECKS.forEach((checkPost) => { 78 78 + for (const checkPost of POST_CHECKS) { 77 79 if (checkPost.language) { 78 80 if (!checkPost.language.includes(lang)) { 79 79 - return; 81 81 + continue; 80 82 } 81 83 } 82 84 ··· 86 88 { process: "CHECKPOSTS", did: post[0].did, atURI: post[0].atURI }, 87 89 "Whitelisted DID", 88 90 ); 89 89 - return; 91 91 + continue; 90 92 } 91 93 } 92 94 ··· 98 100 { process: "CHECKPOSTS", did: post[0].did, atURI: post[0].atURI }, 99 101 "Whitelisted phrase found", 100 102 ); 101 101 - return; 103 103 + continue; 102 104 } 103 105 } 104 106 105 105 - void countStarterPacks(post[0].did, post[0].time); 107 107 + await countStarterPacks(post[0].did, post[0].time); 108 108 + 109 109 + const postURL = `https://pdsls.dev/${post[0].atURI}`; 110 110 + const formattedComment = `${checkPost.comment}\n\nPost: ${postURL}\n\nText: "${post[0].text}"`; 111 111 + 112 112 + const results: ModerationResult = { success: true, errors: [] }; 106 113 107 114 if (checkPost.toLabel) { 108 108 - void createPostLabel( 109 109 - post[0].atURI, 110 110 - post[0].cid, 111 111 - checkPost.label, 112 112 - `${post[0].time.toString()}: ${checkPost.comment} at ${post[0].atURI} with text "${post[0].text}"`, 113 113 - checkPost.duration, 114 114 - post[0].did, 115 115 - post[0].time, 116 116 - ); 115 115 + try { 116 116 + await createPostLabel( 117 117 + post[0].atURI, 118 118 + post[0].cid, 119 119 + checkPost.label, 120 120 + formattedComment, 121 121 + checkPost.duration, 122 122 + post[0].did, 123 123 + post[0].time, 124 124 + ); 125 125 + } catch (error) { 126 126 + results.success = false; 127 127 + results.errors.push({ action: "label", error }); 128 128 + } 129 129 + } else if (checkPost.trackOnly) { 130 130 + try { 131 131 + await checkAccountThreshold( 132 132 + post[0].did, 133 133 + post[0].atURI, 134 134 + checkPost.label, 135 135 + post[0].time, 136 136 + ); 137 137 + } catch (error) { 138 138 + // Threshold check failures are logged but don't add to results.errors 139 139 + // since it's not a direct moderation action 140 140 + logger.error( 141 141 + { 142 142 + process: "CHECKPOSTS", 143 143 + did: post[0].did, 144 144 + atURI: post[0].atURI, 145 145 + error, 146 146 + }, 147 147 + "Account threshold check failed", 148 148 + ); 149 149 + } 117 150 } 118 151 119 152 if (checkPost.reportPost === true) { ··· 126 159 }, 127 160 "Reporting post", 128 161 ); 129 129 - void createPostReport( 130 130 - post[0].atURI, 131 131 - post[0].cid, 132 132 - `${post[0].time.toString()}: ${checkPost.comment} at ${post[0].atURI} with text "${post[0].text}"`, 133 133 - ); 162 162 + try { 163 163 + await createPostReport(post[0].atURI, post[0].cid, formattedComment); 164 164 + } catch (error) { 165 165 + results.success = false; 166 166 + results.errors.push({ action: "report", error }); 167 167 + } 134 168 } 135 169 136 170 if (checkPost.reportAcct) { ··· 143 177 }, 144 178 "Reporting account", 145 179 ); 146 146 - void createAccountReport( 147 147 - post[0].did, 148 148 - `${post[0].time.toString()}: ${checkPost.comment} at ${post[0].atURI} with text "${post[0].text}"`, 149 149 - ); 180 180 + try { 181 181 + await createAccountReport(post[0].did, formattedComment); 182 182 + } catch (error) { 183 183 + results.success = false; 184 184 + results.errors.push({ action: "report", error }); 185 185 + } 150 186 } 151 187 152 188 if (checkPost.commentAcct) { 153 153 - void createAccountComment( 154 154 - post[0].did, 155 155 - `${post[0].time.toString()}: ${checkPost.comment} at ${post[0].atURI} with text "${post[0].text}"`, 156 156 - post[0].atURI, 157 157 - ); 189 189 + try { 190 190 + await createAccountComment( 191 191 + post[0].did, 192 192 + formattedComment, 193 193 + post[0].atURI, 194 194 + ); 195 195 + } catch (error) { 196 196 + results.success = false; 197 197 + results.errors.push({ action: "comment", error }); 198 198 + } 199 199 + } 200 200 + 201 201 + // Log and track any failures 202 202 + if (!results.success) { 203 203 + for (const error of results.errors) { 204 204 + logger.error( 205 205 + { 206 206 + process: "CHECKPOSTS", 207 207 + did: post[0].did, 208 208 + atURI: post[0].atURI, 209 209 + action: error.action, 210 210 + error: error.error, 211 211 + }, 212 212 + "Moderation action failed", 213 213 + ); 214 214 + moderationActionsFailedCounter.inc({ 215 215 + action: error.action, 216 216 + target_type: "post", 217 217 + }); 218 218 + } 158 219 } 159 220 } 160 160 - }); 221 221 + } 161 222 };

+40

src/rules/posts/tests/checkPosts.test.ts

··· 3 3 createAccountComment, 4 4 createAccountReport, 5 5 } from "../../../accountModeration.js"; 6 6 + import { checkAccountThreshold } from "../../../accountThreshold.js"; 6 7 import { logger } from "../../../logger.js"; 7 8 import { createPostLabel, createPostReport } from "../../../moderation.js"; 8 9 import type { Post } from "../../../types.js"; ··· 67 68 reportAcct: true, 68 69 commentAcct: true, 69 70 }, 71 71 + { 72 72 + label: "track-only-label", 73 73 + comment: "Track only test", 74 74 + check: /shopping/i, 75 75 + toLabel: false, 76 76 + trackOnly: true, 77 77 + reportPost: false, 78 78 + reportAcct: false, 79 79 + commentAcct: false, 80 80 + }, 70 81 ], 71 82 })); 72 83 ··· 86 97 vi.mock("../../../accountModeration.js", () => ({ 87 98 createAccountReport: vi.fn(), 88 99 createAccountComment: vi.fn(), 100 100 + })); 101 101 + 102 102 + vi.mock("../../../accountThreshold.js", () => ({ 103 103 + checkAccountThreshold: vi.fn(), 89 104 })); 90 105 91 106 vi.mock("../../../moderation.js", () => ({ ··· 422 437 post[0].did, 423 438 expect.any(String), 424 439 expect.any(String), 440 440 + ); 441 441 + }); 442 442 + }); 443 443 + 444 444 + describe("trackOnly behavior", () => { 445 445 + it("should track for account threshold without emitting post label when trackOnly is true", async () => { 446 446 + const post = createMockPost({ text: "check out this shopping link" }); 447 447 + 448 448 + await checkPosts(post); 449 449 + 450 450 + expect(createPostLabel).not.toHaveBeenCalledWith( 451 451 + expect.any(String), 452 452 + expect.any(String), 453 453 + "track-only-label", 454 454 + expect.any(String), 455 455 + expect.any(Number), 456 456 + expect.any(String), 457 457 + expect.any(Number), 458 458 + ); 459 459 + 460 460 + expect(checkAccountThreshold).toHaveBeenCalledWith( 461 461 + post[0].did, 462 462 + post[0].atURI, 463 463 + "track-only-label", 464 464 + post[0].time, 425 465 ); 426 466 }); 427 467 });

+233 -143

src/rules/profiles/checkProfiles.ts

··· 4 4 createAccountComment, 5 5 createAccountLabel, 6 6 createAccountReport, 7 7 + negateAccountLabel, 7 8 } from "../../accountModeration.js"; 8 9 import { logger } from "../../logger.js"; 10 10 + import { moderationActionsFailedCounter } from "../../metrics.js"; 11 11 + import type { Checks, ModerationResult } from "../../types.js"; 9 12 import { getLanguage } from "../../utils/getLanguage.js"; 10 13 14 14 + export class ProfileChecker { 15 15 + private check: Checks; 16 16 + private did: string; 17 17 + private time: number; 18 18 + 19 19 + constructor(check: Checks, did: string, time: number) { 20 20 + this.check = check; 21 21 + this.did = did; 22 22 + this.time = time; 23 23 + } 24 24 + 25 25 + async checkDescription(description: string): Promise<void> { 26 26 + if (!description) return; 27 27 + await this.performActions(description, "CHECKDESCRIPTION"); 28 28 + } 29 29 + 30 30 + async checkDisplayName(displayName: string): Promise<void> { 31 31 + if (!displayName) return; 32 32 + await this.performActions(displayName, "CHECKDISPLAYNAME"); 33 33 + } 34 34 + 35 35 + async checkBoth(displayName: string, description: string): Promise<void> { 36 36 + const profile = `${displayName} ${description}`; 37 37 + if (!profile) return; 38 38 + await this.performActions(profile, "CHECKPROFILE"); 39 39 + } 40 40 + 41 41 + private async performActions( 42 42 + content: string, 43 43 + processType: "CHECKPROFILE" | "CHECKDESCRIPTION" | "CHECKDISPLAYNAME", 44 44 + ): Promise<void> { 45 45 + const matched = this.check.check.test(content); 46 46 + 47 47 + if (matched) { 48 48 + if (this.check.whitelist?.test(content)) { 49 49 + logger.debug( 50 50 + { process: processType, did: this.did, time: this.time, content }, 51 51 + "Whitelisted phrase found", 52 52 + ); 53 53 + return; 54 54 + } 55 55 + 56 56 + const result = await this.applyActions(content, processType); 57 57 + if (!result.success) { 58 58 + for (const error of result.errors) { 59 59 + logger.error( 60 60 + { 61 61 + process: processType, 62 62 + did: this.did, 63 63 + action: error.action, 64 64 + error: error.error, 65 65 + }, 66 66 + "Moderation action failed", 67 67 + ); 68 68 + moderationActionsFailedCounter.inc({ 69 69 + action: error.action, 70 70 + target_type: "account", 71 71 + }); 72 72 + } 73 73 + } 74 74 + } else { 75 75 + if (this.check.unlabel) { 76 76 + const result = await this.removeLabel(content, processType); 77 77 + if (!result.success) { 78 78 + for (const error of result.errors) { 79 79 + logger.error( 80 80 + { 81 81 + process: processType, 82 82 + did: this.did, 83 83 + action: error.action, 84 84 + error: error.error, 85 85 + }, 86 86 + "Moderation action failed", 87 87 + ); 88 88 + moderationActionsFailedCounter.inc({ 89 89 + action: error.action, 90 90 + target_type: "account", 91 91 + }); 92 92 + } 93 93 + } 94 94 + } 95 95 + } 96 96 + } 97 97 + 98 98 + private async applyActions( 99 99 + content: string, 100 100 + processType: string, 101 101 + ): Promise<ModerationResult> { 102 102 + const results: ModerationResult = { success: true, errors: [] }; 103 103 + const formattedComment = `${this.time.toString()}: ${this.check.comment}\n\nContent: ${content}`; 104 104 + 105 105 + if (this.check.toLabel) { 106 106 + try { 107 107 + await createAccountLabel(this.did, this.check.label, formattedComment); 108 108 + } catch (error) { 109 109 + results.success = false; 110 110 + results.errors.push({ action: "label", error }); 111 111 + } 112 112 + } 113 113 + 114 114 + if (this.check.reportAcct) { 115 115 + try { 116 116 + await createAccountReport(this.did, formattedComment); 117 117 + logger.info( 118 118 + { 119 119 + process: processType, 120 120 + did: this.did, 121 121 + time: this.time, 122 122 + label: this.check.label, 123 123 + }, 124 124 + "Reporting account", 125 125 + ); 126 126 + } catch (error) { 127 127 + results.success = false; 128 128 + results.errors.push({ action: "report", error }); 129 129 + } 130 130 + } 131 131 + 132 132 + if (this.check.commentAcct) { 133 133 + try { 134 134 + await createAccountComment( 135 135 + this.did, 136 136 + formattedComment, 137 137 + `profile:${this.did}`, 138 138 + ); 139 139 + } catch (error) { 140 140 + results.success = false; 141 141 + results.errors.push({ action: "comment", error }); 142 142 + } 143 143 + } 144 144 + 145 145 + return results; 146 146 + } 147 147 + 148 148 + private async removeLabel( 149 149 + content: string, 150 150 + _processType: string, 151 151 + ): Promise<ModerationResult> { 152 152 + const results: ModerationResult = { success: true, errors: [] }; 153 153 + const formattedComment = `${this.check.comment}\n\nContent: ${content}`; 154 154 + try { 155 155 + await negateAccountLabel(this.did, this.check.label, formattedComment); 156 156 + } catch (error) { 157 157 + results.success = false; 158 158 + results.errors.push({ action: "unlabel", error }); 159 159 + } 160 160 + return results; 161 161 + } 162 162 + } 163 163 + 11 164 export const checkDescription = async ( 12 165 did: string, 13 166 time: number, 14 167 displayName: string, 15 168 description: string, 16 16 - ) => { 17 17 - const lang = await getLanguage(description); 169 169 + ): Promise<void> => { 170 170 + if (!description) return; 18 171 19 19 - // Check if DID is whitelisted 20 172 if (GLOBAL_ALLOW.includes(did)) { 21 173 logger.warn( 22 174 { process: "CHECKDESCRIPTION", did, time, displayName, description }, ··· 25 177 return; 26 178 } 27 179 28 28 - // iterate through the checks 29 29 - PROFILE_CHECKS.forEach((checkProfiles) => { 30 30 - if (checkProfiles.language) { 31 31 - if (!checkProfiles.language.includes(lang)) { 32 32 - return; 180 180 + for (const checkRule of PROFILE_CHECKS) { 181 181 + if (checkRule.language) { 182 182 + const lang = await getLanguage(description); 183 183 + if (!checkRule.language.includes(lang)) { 184 184 + continue; 33 185 } 34 186 } 35 187 36 36 - // Check if DID is whitelisted 37 37 - if (checkProfiles.ignoredDIDs) { 38 38 - if (checkProfiles.ignoredDIDs.includes(did)) { 39 39 - logger.debug( 40 40 - { process: "CHECKDESCRIPTION", did, time, displayName, description }, 41 41 - "Whitelisted DID", 42 42 - ); 43 43 - return; 44 44 - } 188 188 + if (checkRule.ignoredDIDs?.includes(did)) { 189 189 + logger.debug( 190 190 + { process: "CHECKDESCRIPTION", did, time, displayName, description }, 191 191 + "Whitelisted DID", 192 192 + ); 193 193 + continue; 45 194 } 46 195 47 47 - if (description) { 48 48 - if (checkProfiles.description === true) { 49 49 - if (checkProfiles.check.test(description)) { 50 50 - // Check if description is whitelisted 51 51 - if (checkProfiles.whitelist) { 52 52 - if (checkProfiles.whitelist.test(description)) { 53 53 - logger.debug( 54 54 - { 55 55 - process: "CHECKDESCRIPTION", 56 56 - did, 57 57 - time, 58 58 - displayName, 59 59 - description, 60 60 - }, 61 61 - "Whitelisted phrase found", 62 62 - ); 63 63 - return; 64 64 - } 65 65 - } 66 66 - 67 67 - if (checkProfiles.toLabel) { 68 68 - void createAccountLabel( 69 69 - did, 70 70 - checkProfiles.label, 71 71 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 72 72 - ); 73 73 - } 74 74 - 75 75 - if (checkProfiles.reportAcct) { 76 76 - void createAccountReport( 77 77 - did, 78 78 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 79 79 - ); 80 80 - logger.info( 81 81 - { 82 82 - process: "CHECKDESCRIPTION", 83 83 - did, 84 84 - time, 85 85 - displayName, 86 86 - description, 87 87 - label: checkProfiles.label, 88 88 - }, 89 89 - "Reporting account", 90 90 - ); 91 91 - } 92 92 - 93 93 - if (checkProfiles.commentAcct) { 94 94 - void createAccountComment( 95 95 - did, 96 96 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 97 97 - `profile:${did}:${time.toString()}`, 98 98 - ); 99 99 - } 100 100 - } 101 101 - } 196 196 + if (checkRule.description === true) { 197 197 + const checker = new ProfileChecker(checkRule, did, time); 198 198 + await checker.checkDescription(description); 102 199 } 103 103 - }); 200 200 + } 104 201 }; 105 202 106 203 export const checkDisplayName = async ( ··· 108 205 time: number, 109 206 displayName: string, 110 207 description: string, 111 111 - ) => { 112 112 - // Check if DID is whitelisted 208 208 + ): Promise<void> => { 209 209 + if (!displayName) return; 210 210 + 113 211 if (GLOBAL_ALLOW.includes(did)) { 114 212 logger.warn( 115 213 { process: "CHECKDISPLAYNAME", did, time, displayName, description }, ··· 118 216 return; 119 217 } 120 218 121 121 - const lang = await getLanguage(description); 122 122 - 123 123 - // iterate through the checks 124 124 - PROFILE_CHECKS.forEach((checkProfiles) => { 125 125 - if (checkProfiles.language) { 126 126 - if (!checkProfiles.language.includes(lang)) { 127 127 - return; 219 219 + for (const checkRule of PROFILE_CHECKS) { 220 220 + if (checkRule.language) { 221 221 + const lang = await getLanguage(displayName); 222 222 + if (!checkRule.language.includes(lang)) { 223 223 + continue; 128 224 } 129 225 } 130 226 131 131 - // Check if DID is whitelisted 132 132 - if (checkProfiles.ignoredDIDs) { 133 133 - if (checkProfiles.ignoredDIDs.includes(did)) { 134 134 - logger.debug( 135 135 - { process: "CHECKDISPLAYNAME", did, time, displayName, description }, 136 136 - "Whitelisted DID", 137 137 - ); 138 138 - return; 139 139 - } 227 227 + if (checkRule.ignoredDIDs?.includes(did)) { 228 228 + logger.debug( 229 229 + { process: "CHECKDISPLAYNAME", did, time, displayName, description }, 230 230 + "Whitelisted DID", 231 231 + ); 232 232 + continue; 140 233 } 141 234 142 142 - if (displayName) { 143 143 - if (checkProfiles.displayName === true) { 144 144 - if (checkProfiles.check.test(displayName)) { 145 145 - // Check if displayName is whitelisted 146 146 - if (checkProfiles.whitelist) { 147 147 - if (checkProfiles.whitelist.test(displayName)) { 148 148 - logger.debug( 149 149 - { 150 150 - process: "CHECKDISPLAYNAME", 151 151 - did, 152 152 - time, 153 153 - displayName, 154 154 - description, 155 155 - }, 156 156 - "Whitelisted phrase found", 157 157 - ); 158 158 - return; 159 159 - } 160 160 - } 235 235 + if (checkRule.displayName === true) { 236 236 + const checker = new ProfileChecker(checkRule, did, time); 237 237 + await checker.checkDisplayName(displayName); 238 238 + } 239 239 + } 240 240 + }; 161 241 162 162 - if (checkProfiles.toLabel) { 163 163 - void createAccountLabel( 164 164 - did, 165 165 - checkProfiles.label, 166 166 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 167 167 - ); 168 168 - } 242 242 + export const checkProfile = async ( 243 243 + did: string, 244 244 + time: number, 245 245 + displayName: string, 246 246 + description: string, 247 247 + ) => { 248 248 + const profile = `${displayName} ${description}`; 249 249 + const lang = await getLanguage(profile); 169 250 170 170 - if (checkProfiles.reportAcct) { 171 171 - void createAccountReport( 172 172 - did, 173 173 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 174 174 - ); 175 175 - logger.info( 176 176 - { 177 177 - process: "CHECKDISPLAYNAME", 178 178 - did, 179 179 - time, 180 180 - displayName, 181 181 - description, 182 182 - label: checkProfiles.label, 183 183 - }, 184 184 - "Reporting account", 185 185 - ); 186 186 - } 251 251 + // Check if DID is whitelisted at global level 252 252 + if (GLOBAL_ALLOW.includes(did)) { 253 253 + logger.warn( 254 254 + { process: "CHECKPROFILE", did, time, profile }, 255 255 + "Global AllowListed DID", 256 256 + ); 257 257 + return; 258 258 + } 187 259 188 188 - if (checkProfiles.commentAcct) { 189 189 - void createAccountComment( 190 190 - did, 191 191 - `${time.toString()}: ${checkProfiles.comment} - ${displayName} - ${description}`, 192 192 - `profile:${did}:${time.toString()}`, 193 193 - ); 194 194 - } 195 195 - } 260 260 + // Iterate through checks and delegate to ProfileChecker 261 261 + for (const checkRule of PROFILE_CHECKS) { 262 262 + // Language filter (same for all branches) 263 263 + if (checkRule.language) { 264 264 + if (!checkRule.language.includes(lang)) { 265 265 + continue; 196 266 } 197 267 } 198 198 - }); 268 268 + 269 269 + // DID whitelist (same for all branches) 270 270 + if (checkRule.ignoredDIDs?.includes(did)) { 271 271 + logger.debug( 272 272 + { process: "CHECKPROFILE", did, time, displayName, description }, 273 273 + "Whitelisted DID", 274 274 + ); 275 275 + continue; 276 276 + } 277 277 + 278 278 + // Dispatch to correct method based on check configuration 279 279 + const checker = new ProfileChecker(checkRule, did, time); 280 280 + 281 281 + if (checkRule.description === true && checkRule.displayName === true) { 282 282 + await checker.checkBoth(displayName, description); 283 283 + } else if (checkRule.description === true) { 284 284 + await checker.checkDescription(description); 285 285 + } else if (checkRule.displayName === true) { 286 286 + await checker.checkDisplayName(displayName); 287 287 + } 288 288 + } 199 289 };

+1 -2

src/rules/profiles/tests/checkProfiles.test.ts

··· 263 263 process: "CHECKDESCRIPTION", 264 264 did: mockDid, 265 265 time: mockTime, 266 266 - displayName: mockDisplayName, 267 267 - description: "this is good bad content", 266 266 + content: "this is good bad content", 268 267 }, 269 268 "Whitelisted phrase found", 270 269 );

+158

src/starterPackThreshold.ts

··· 1 1 + import { STARTER_PACK_THRESHOLD_CONFIGS } from "../rules/starterPackThreshold.js"; 2 2 + import { 3 3 + createAccountComment, 4 4 + createAccountLabel, 5 5 + createAccountReport, 6 6 + } from "./accountModeration.js"; 7 7 + import { logger } from "./logger.js"; 8 8 + import { 9 9 + starterPackLabelsThresholdAppliedCounter, 10 10 + starterPackThresholdChecksCounter, 11 11 + starterPackThresholdMetCounter, 12 12 + } from "./metrics.js"; 13 13 + import { 14 14 + getStarterPackCountInWindow, 15 15 + trackStarterPackForAccount, 16 16 + } from "./redis.js"; 17 17 + import type { StarterPackThresholdConfig } from "./types.js"; 18 18 + 19 19 + function validateAndLoadConfigs(): StarterPackThresholdConfig[] { 20 20 + if (STARTER_PACK_THRESHOLD_CONFIGS.length === 0) { 21 21 + logger.warn( 22 22 + { process: "STARTER_PACK_THRESHOLD" }, 23 23 + "No starter pack threshold configs found", 24 24 + ); 25 25 + return []; 26 26 + } 27 27 + 28 28 + for (const config of STARTER_PACK_THRESHOLD_CONFIGS) { 29 29 + if (config.threshold <= 0) { 30 30 + throw new Error( 31 31 + `Invalid starter pack threshold config: threshold must be positive`, 32 32 + ); 33 33 + } 34 34 + if (config.window <= 0) { 35 35 + throw new Error( 36 36 + `Invalid starter pack threshold config: window must be positive`, 37 37 + ); 38 38 + } 39 39 + } 40 40 + 41 41 + logger.info( 42 42 + { process: "STARTER_PACK_THRESHOLD", count: STARTER_PACK_THRESHOLD_CONFIGS.length }, 43 43 + "Loaded starter pack threshold configs", 44 44 + ); 45 45 + 46 46 + return STARTER_PACK_THRESHOLD_CONFIGS; 47 47 + } 48 48 + 49 49 + const cachedConfigs = validateAndLoadConfigs(); 50 50 + 51 51 + export function loadStarterPackThresholdConfigs(): StarterPackThresholdConfig[] { 52 52 + return cachedConfigs; 53 53 + } 54 54 + 55 55 + export async function checkStarterPackThreshold( 56 56 + did: string, 57 57 + starterPackUri: string, 58 58 + timestamp: number, 59 59 + ): Promise<void> { 60 60 + try { 61 61 + const configs = loadStarterPackThresholdConfigs(); 62 62 + 63 63 + if (configs.length === 0) { 64 64 + return; 65 65 + } 66 66 + 67 67 + starterPackThresholdChecksCounter.inc(); 68 68 + 69 69 + for (const config of configs) { 70 70 + // Check allowlist 71 71 + if (config.allowlist?.includes(did)) { 72 72 + logger.debug( 73 73 + { process: "STARTER_PACK_THRESHOLD", did, starterPackUri }, 74 74 + "Account is in allowlist, skipping threshold check", 75 75 + ); 76 76 + continue; 77 77 + } 78 78 + 79 79 + await trackStarterPackForAccount( 80 80 + did, 81 81 + starterPackUri, 82 82 + timestamp, 83 83 + config.window, 84 84 + config.windowUnit, 85 85 + ); 86 86 + 87 87 + const count = await getStarterPackCountInWindow( 88 88 + did, 89 89 + config.window, 90 90 + config.windowUnit, 91 91 + timestamp, 92 92 + ); 93 93 + 94 94 + logger.debug( 95 95 + { 96 96 + process: "STARTER_PACK_THRESHOLD", 97 97 + did, 98 98 + count, 99 99 + threshold: config.threshold, 100 100 + window: config.window, 101 101 + windowUnit: config.windowUnit, 102 102 + }, 103 103 + "Checked starter pack threshold", 104 104 + ); 105 105 + 106 106 + if (count >= config.threshold) { 107 107 + starterPackThresholdMetCounter.inc({ account_label: config.accountLabel }); 108 108 + 109 109 + logger.info( 110 110 + { 111 111 + process: "STARTER_PACK_THRESHOLD", 112 112 + did, 113 113 + starterPackUri, 114 114 + accountLabel: config.accountLabel, 115 115 + count, 116 116 + threshold: config.threshold, 117 117 + }, 118 118 + "Starter pack threshold met", 119 119 + ); 120 120 + 121 121 + const shouldLabel = config.toLabel !== false; 122 122 + 123 123 + const formattedComment = `${config.accountComment}\n\nThreshold: ${count.toString()}/${config.threshold.toString()} in ${config.window.toString()} ${config.windowUnit}\n\nStarter Pack: ${starterPackUri}`; 124 124 + 125 125 + if (shouldLabel) { 126 126 + await createAccountLabel(did, config.accountLabel, formattedComment); 127 127 + starterPackLabelsThresholdAppliedCounter.inc({ 128 128 + account_label: config.accountLabel, 129 129 + action: "label", 130 130 + }); 131 131 + } 132 132 + 133 133 + if (config.reportAcct) { 134 134 + await createAccountReport(did, formattedComment); 135 135 + starterPackLabelsThresholdAppliedCounter.inc({ 136 136 + account_label: config.accountLabel, 137 137 + action: "report", 138 138 + }); 139 139 + } 140 140 + 141 141 + if (config.commentAcct) { 142 142 + const atURI = `starterpack-threshold-comment:${config.accountLabel}:${timestamp.toString()}`; 143 143 + await createAccountComment(did, formattedComment, atURI); 144 144 + starterPackLabelsThresholdAppliedCounter.inc({ 145 145 + account_label: config.accountLabel, 146 146 + action: "comment", 147 147 + }); 148 148 + } 149 149 + } 150 150 + } 151 151 + } catch (error) { 152 152 + logger.error( 153 153 + { process: "STARTER_PACK_THRESHOLD", did, starterPackUri, error }, 154 154 + "Error checking starter pack threshold", 155 155 + ); 156 156 + throw error; 157 157 + } 158 158 + }

+216

src/tests/accountModeration.test.ts

··· 1 1 + import { describe, it, expect, vi, beforeEach } from "vitest"; 2 2 + import { getAllAccountLabels, negateAccountLabel } from "../accountModeration.js"; 3 3 + import { agent } from "../agent.js"; 4 4 + 5 5 + vi.mock("../agent.js", () => ({ 6 6 + agent: { 7 7 + did: "did:plc:test-moderator", 8 8 + tools: { 9 9 + ozone: { 10 10 + moderation: { 11 11 + getRepo: vi.fn(), 12 12 + emitEvent: vi.fn(), 13 13 + }, 14 14 + }, 15 15 + }, 16 16 + }, 17 17 + isLoggedIn: Promise.resolve(), 18 18 + })); 19 19 + 20 20 + vi.mock("../logger.js", () => ({ 21 21 + logger: { 22 22 + info: vi.fn(), 23 23 + debug: vi.fn(), 24 24 + error: vi.fn(), 25 25 + warn: vi.fn(), 26 26 + }, 27 27 + })); 28 28 + 29 29 + vi.mock("../limits.js", () => ({ 30 30 + limit: vi.fn((fn) => fn()), 31 31 + })); 32 32 + 33 33 + vi.mock("../redis.js", () => ({ 34 34 + deleteAccountLabelClaim: vi.fn().mockResolvedValue(undefined), 35 35 + })); 36 36 + 37 37 + vi.mock("../metrics.js", () => ({ 38 38 + unlabelsRemovedCounter: { 39 39 + inc: vi.fn(), 40 40 + }, 41 41 + labelsAppliedCounter: { 42 42 + inc: vi.fn(), 43 43 + }, 44 44 + labelsCachedCounter: { 45 45 + inc: vi.fn(), 46 46 + }, 47 47 + })); 48 48 + 49 49 + const mockAgent = agent as any; 50 50 + 51 51 + describe("getAllAccountLabels", () => { 52 52 + beforeEach(() => { 53 53 + vi.clearAllMocks(); 54 54 + }); 55 55 + 56 56 + it("should return array of label strings from API response", async () => { 57 57 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 58 58 + data: { 59 59 + labels: [{ val: "blue-heart-emoji" }, { val: "hammer-sickle" }], 60 60 + }, 61 61 + }); 62 62 + 63 63 + const labels = await getAllAccountLabels("did:plc:test123"); 64 64 + 65 65 + expect(labels).toEqual(["blue-heart-emoji", "hammer-sickle"]); 66 66 + expect(mockAgent.tools.ozone.moderation.getRepo).toHaveBeenCalledWith( 67 67 + { did: "did:plc:test123" }, 68 68 + expect.objectContaining({ 69 69 + headers: expect.any(Object), 70 70 + }), 71 71 + ); 72 72 + }); 73 73 + 74 74 + it("should return empty array when account has no labels", async () => { 75 75 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 76 76 + data: { 77 77 + labels: undefined, 78 78 + }, 79 79 + }); 80 80 + 81 81 + const labels = await getAllAccountLabels("did:plc:test123"); 82 82 + 83 83 + expect(labels).toEqual([]); 84 84 + }); 85 85 + 86 86 + it("should return empty array when labels array is empty", async () => { 87 87 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 88 88 + data: { 89 89 + labels: [], 90 90 + }, 91 91 + }); 92 92 + 93 93 + const labels = await getAllAccountLabels("did:plc:test123"); 94 94 + 95 95 + expect(labels).toEqual([]); 96 96 + }); 97 97 + 98 98 + it("should return empty array on API error", async () => { 99 99 + mockAgent.tools.ozone.moderation.getRepo.mockRejectedValueOnce( 100 100 + new Error("API Error"), 101 101 + ); 102 102 + 103 103 + const labels = await getAllAccountLabels("did:plc:test123"); 104 104 + 105 105 + expect(labels).toEqual([]); 106 106 + }); 107 107 + }); 108 108 + 109 109 + describe("negateAccountLabel", () => { 110 110 + beforeEach(() => { 111 111 + vi.clearAllMocks(); 112 112 + }); 113 113 + 114 114 + it("should emit moderation event to remove label", async () => { 115 115 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 116 116 + data: { 117 117 + labels: [{ val: "blue-heart-emoji" }], 118 118 + }, 119 119 + }); 120 120 + 121 121 + mockAgent.tools.ozone.moderation.emitEvent.mockResolvedValueOnce({}); 122 122 + 123 123 + await negateAccountLabel( 124 124 + "did:plc:test123", 125 125 + "blue-heart-emoji", 126 126 + "Test removal", 127 127 + ); 128 128 + 129 129 + expect(mockAgent.tools.ozone.moderation.emitEvent).toHaveBeenCalledWith( 130 130 + expect.objectContaining({ 131 131 + event: expect.objectContaining({ 132 132 + $type: "tools.ozone.moderation.defs#modEventLabel", 133 133 + createLabelVals: [], 134 134 + negateLabelVals: ["blue-heart-emoji"], 135 135 + comment: "Test removal", 136 136 + }), 137 137 + subject: expect.objectContaining({ 138 138 + $type: "com.atproto.admin.defs#repoRef", 139 139 + did: "did:plc:test123", 140 140 + }), 141 141 + }), 142 142 + expect.any(Object), 143 143 + ); 144 144 + }); 145 145 + 146 146 + it("should not emit event if label does not exist on account", async () => { 147 147 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 148 148 + data: { 149 149 + labels: [{ val: "other-label" }], 150 150 + }, 151 151 + }); 152 152 + 153 153 + await negateAccountLabel( 154 154 + "did:plc:test123", 155 155 + "blue-heart-emoji", 156 156 + "Test removal", 157 157 + ); 158 158 + 159 159 + expect(mockAgent.tools.ozone.moderation.emitEvent).not.toHaveBeenCalled(); 160 160 + }); 161 161 + 162 162 + it("should not emit event if account has no labels", async () => { 163 163 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 164 164 + data: { 165 165 + labels: [], 166 166 + }, 167 167 + }); 168 168 + 169 169 + await negateAccountLabel( 170 170 + "did:plc:test123", 171 171 + "blue-heart-emoji", 172 172 + "Test removal", 173 173 + ); 174 174 + 175 175 + expect(mockAgent.tools.ozone.moderation.emitEvent).not.toHaveBeenCalled(); 176 176 + }); 177 177 + 178 178 + it("should delete Redis cache key on successful removal", async () => { 179 179 + const { deleteAccountLabelClaim } = await import("../redis.js"); 180 180 + 181 181 + mockAgent.tools.ozone.moderation.getRepo.mockResolvedValueOnce({ 182 182 + data: { 183 183 + labels: [{ val: "blue-heart-emoji" }], 184 184 + }, 185 185 + }); 186 186 + 187 187 + mockAgent.tools.ozone.moderation.emitEvent.mockResolvedValueOnce({}); 188 188 + 189 189 + await negateAccountLabel( 190 190 + "did:plc:test123", 191 191 + "blue-heart-emoji", 192 192 + "Test removal", 193 193 + ); 194 194 + 195 195 + expect(deleteAccountLabelClaim).toHaveBeenCalledWith( 196 196 + "did:plc:test123", 197 197 + "blue-heart-emoji", 198 198 + ); 199 199 + }); 200 200 + 201 201 + it("should log error if API call fails", async () => { 202 202 + const { logger } = await import("../logger.js"); 203 203 + 204 204 + mockAgent.tools.ozone.moderation.getRepo.mockRejectedValueOnce( 205 205 + new Error("API Error"), 206 206 + ); 207 207 + 208 208 + await negateAccountLabel( 209 209 + "did:plc:test123", 210 210 + "blue-heart-emoji", 211 211 + "Test removal", 212 212 + ); 213 213 + 214 214 + expect(logger.error).toHaveBeenCalled(); 215 215 + }); 216 216 + });

+35 -17

src/tests/accountThreshold.test.ts

··· 35 35 threshold: 3, 36 36 accountLabel: "test-account-label", 37 37 accountComment: "Test comment", 38 38 - windowDays: 5, 38 38 + window: 5, 39 39 + windowUnit: "days", 39 40 reportAcct: false, 40 41 commentAcct: false, 41 42 toLabel: true, ··· 45 46 threshold: 5, 46 47 accountLabel: "multi-label-account", 47 48 accountComment: "Multi label comment", 48 48 - windowDays: 7, 49 49 + window: 7, 50 50 + windowUnit: "days", 49 51 reportAcct: true, 50 52 commentAcct: true, 51 53 toLabel: true, ··· 55 57 threshold: 2, 56 58 accountLabel: "monitored", 57 59 accountComment: "Monitoring comment", 58 58 - windowDays: 3, 60 60 + window: 3, 61 61 + windowUnit: "days", 59 62 reportAcct: true, 60 63 commentAcct: false, 61 64 toLabel: false, ··· 65 68 threshold: 2, 66 69 accountLabel: "shared-config", 67 70 accountComment: "Shared config comment", 68 68 - windowDays: 4, 71 71 + window: 4, 72 72 + windowUnit: "days", 69 73 reportAcct: false, 70 74 commentAcct: false, 71 75 toLabel: true, ··· 118 122 119 123 describe("checkAccountThreshold", () => { 120 124 const testDid = "did:plc:test123"; 125 125 + const testUri = "at://did:plc:test123/app.bsky.feed.post/abc123"; 121 126 const testTimestamp = 1640000000000000; 122 127 123 128 it("should not check threshold for non-matching labels", async () => { 124 129 vi.mocked(trackPostLabelForAccount).mockResolvedValue(); 125 130 vi.mocked(getPostLabelCountInWindow).mockResolvedValue(0); 126 131 127 127 - await checkAccountThreshold(testDid, "non-matching-label", testTimestamp); 132 132 + await checkAccountThreshold( 133 133 + testDid, 134 134 + testUri, 135 135 + "non-matching-label", 136 136 + testTimestamp, 137 137 + ); 128 138 129 139 expect(trackPostLabelForAccount).not.toHaveBeenCalled(); 130 140 expect(getPostLabelCountInWindow).not.toHaveBeenCalled(); ··· 134 144 vi.mocked(trackPostLabelForAccount).mockResolvedValue(); 135 145 vi.mocked(getPostLabelCountInWindow).mockResolvedValue(2); 136 146 137 137 - await checkAccountThreshold(testDid, "test-label", testTimestamp); 147 147 + await checkAccountThreshold(testDid, testUri, "test-label", testTimestamp); 138 148 139 149 expect(accountThresholdChecksCounter.inc).toHaveBeenCalledWith({ 140 150 post_label: "test-label", ··· 144 154 "test-label", 145 155 testTimestamp, 146 156 5, 157 157 + "days", 147 158 ); 148 159 expect(getPostLabelCountInWindow).toHaveBeenCalledWith( 149 160 testDid, 150 161 ["test-label"], 151 162 5, 163 163 + "days", 152 164 testTimestamp, 153 165 ); 154 166 }); ··· 158 170 vi.mocked(getPostLabelCountInWindow).mockResolvedValue(3); 159 171 vi.mocked(createAccountLabel).mockResolvedValue(); 160 172 161 161 - await checkAccountThreshold(testDid, "test-label", testTimestamp); 173 173 + await checkAccountThreshold(testDid, testUri, "test-label", testTimestamp); 162 174 163 175 expect(accountThresholdMetCounter.inc).toHaveBeenCalledWith({ 164 176 account_label: "test-account-label", ··· 166 178 expect(createAccountLabel).toHaveBeenCalledWith( 167 179 testDid, 168 180 "test-account-label", 169 169 - "Test comment", 181 181 + `Test comment\n\nThreshold: 3/3 in 5 days\n\nPost: ${testUri}\n\nPost Label: test-label`, 170 182 ); 171 183 expect(accountLabelsThresholdAppliedCounter.inc).toHaveBeenCalledWith({ 172 184 account_label: "test-account-label", ··· 178 190 vi.mocked(trackPostLabelForAccount).mockResolvedValue(); 179 191 vi.mocked(getPostLabelCountInWindow).mockResolvedValue(2); 180 192 181 181 - await checkAccountThreshold(testDid, "test-label", testTimestamp); 193 193 + await checkAccountThreshold(testDid, testUri, "test-label", testTimestamp); 182 194 183 195 expect(accountThresholdMetCounter.inc).not.toHaveBeenCalled(); 184 196 expect(createAccountLabel).not.toHaveBeenCalled(); ··· 191 203 vi.mocked(createAccountReport).mockResolvedValue(); 192 204 vi.mocked(createAccountComment).mockResolvedValue(); 193 205 194 194 - await checkAccountThreshold(testDid, "label-2", testTimestamp); 206 206 + await checkAccountThreshold(testDid, testUri, "label-2", testTimestamp); 195 207 196 208 expect(getPostLabelCountInWindow).toHaveBeenCalledWith( 197 209 testDid, 198 210 ["label-1", "label-2", "label-3"], 199 211 7, 212 212 + "days", 200 213 testTimestamp, 201 214 ); 202 215 expect(createAccountLabel).toHaveBeenCalledWith( 203 216 testDid, 204 217 "multi-label-account", 205 205 - "Multi label comment", 218 218 + `Multi label comment\n\nThreshold: 5/5 in 7 days\n\nPost: ${testUri}\n\nPost Label: label-2`, 206 219 ); 207 220 expect(createAccountReport).toHaveBeenCalledWith( 208 221 testDid, 209 209 - "Multi label comment", 222 222 + `Multi label comment\n\nThreshold: 5/5 in 7 days\n\nPost: ${testUri}\n\nPost Label: label-2`, 210 223 ); 211 224 expect(createAccountComment).toHaveBeenCalled(); 212 225 }); ··· 216 229 vi.mocked(getPostLabelCountInWindow).mockResolvedValue(2); 217 230 vi.mocked(createAccountReport).mockResolvedValue(); 218 231 219 219 - await checkAccountThreshold(testDid, "monitor-only-label", testTimestamp); 232 232 + await checkAccountThreshold( 233 233 + testDid, 234 234 + testUri, 235 235 + "monitor-only-label", 236 236 + testTimestamp, 237 237 + ); 220 238 221 239 expect(trackPostLabelForAccount).toHaveBeenCalled(); 222 240 expect(getPostLabelCountInWindow).toHaveBeenCalled(); ··· 237 255 vi.mocked(createAccountReport).mockResolvedValue(); 238 256 vi.mocked(createAccountComment).mockResolvedValue(); 239 257 240 240 - await checkAccountThreshold(testDid, "label-1", testTimestamp); 258 258 + await checkAccountThreshold(testDid, testUri, "label-1", testTimestamp); 241 259 242 260 expect(accountLabelsThresholdAppliedCounter.inc).toHaveBeenCalledTimes(3); 243 261 expect(accountLabelsThresholdAppliedCounter.inc).toHaveBeenCalledWith({ ··· 259 277 vi.mocked(trackPostLabelForAccount).mockRejectedValue(redisError); 260 278 261 279 await expect( 262 262 - checkAccountThreshold(testDid, "test-label", testTimestamp), 280 280 + checkAccountThreshold(testDid, testUri, "test-label", testTimestamp), 263 281 ).rejects.toThrow("Redis connection failed"); 264 282 265 283 expect(logger.error).toHaveBeenCalled(); ··· 271 289 vi.mocked(getPostLabelCountInWindow).mockRejectedValue(redisError); 272 290 273 291 await expect( 274 274 - checkAccountThreshold(testDid, "test-label", testTimestamp), 292 292 + checkAccountThreshold(testDid, testUri, "test-label", testTimestamp), 275 293 ).rejects.toThrow("Redis query failed"); 276 294 277 295 expect(logger.error).toHaveBeenCalled(); ··· 286 304 vi.mocked(createAccountReport).mockResolvedValue(); 287 305 vi.mocked(createAccountComment).mockResolvedValue(); 288 306 289 289 - await checkAccountThreshold(testDid, "label-1", testTimestamp); 307 307 + await checkAccountThreshold(testDid, testUri, "label-1", testTimestamp); 290 308 291 309 expect(trackPostLabelForAccount).toHaveBeenCalledTimes(2); 292 310 expect(getPostLabelCountInWindow).toHaveBeenCalledTimes(2);

+12 -1

src/tests/agent.test.ts

··· 13 13 OZONE_PDS: "pds.test.com", 14 14 })); 15 15 16 16 + // Mock session 17 17 + const mockSession = { 18 18 + did: "did:plc:test123", 19 19 + handle: "test.bsky.social", 20 20 + accessJwt: "test-access-jwt", 21 21 + refreshJwt: "test-refresh-jwt", 22 22 + }; 23 23 + 16 24 // Mock the AtpAgent 17 17 - const mockLogin = vi.fn(() => Promise.resolve()); 25 25 + const mockLogin = vi.fn(() => 26 26 + Promise.resolve({ success: true, data: mockSession }), 27 27 + ); 18 28 const mockConstructor = vi.fn(); 19 29 vi.doMock("@atproto/api", () => ({ 20 30 AtpAgent: class { 21 31 login = mockLogin; 22 32 service: URL; 33 33 + session = mockSession; 23 34 constructor(options: { service: string }) { 24 35 mockConstructor(options); 25 36 this.service = new URL(options.service);

+111 -11

src/tests/redis.test.ts

··· 7 7 connectRedis, 8 8 disconnectRedis, 9 9 getPostLabelCountInWindow, 10 10 + getStarterPackCountInWindow, 10 11 trackPostLabelForAccount, 12 12 + trackStarterPackForAccount, 11 13 tryClaimAccountLabel, 12 14 tryClaimPostLabel, 13 15 } from "../redis.js"; ··· 116 118 vi.mocked(mockRedisClient.expire).mockResolvedValue(true); 117 119 118 120 const timestamp = 1640000000000000; // microseconds 119 119 - const windowDays = 5; 121 121 + const window = 5; 122 122 + const windowUnit = "days" as const; 120 123 121 124 await trackPostLabelForAccount( 122 125 "did:plc:123", 123 126 "test-label", 124 127 timestamp, 125 125 - windowDays, 128 128 + window, 129 129 + windowUnit, 126 130 ); 127 131 128 128 - const expectedKey = "account-post-labels:did:plc:123:test-label:5"; 129 129 - const windowStartTime = timestamp - windowDays * 24 * 60 * 60 * 1000000; 132 132 + const expectedKey = "account-post-labels:did:plc:123:test-label:5days"; 133 133 + const windowStartTime = timestamp - window * 24 * 60 * 60 * 1000000; 130 134 131 135 expect(mockRedisClient.zRemRangeByScore).toHaveBeenCalledWith( 132 136 expectedKey, ··· 139 143 }); 140 144 expect(mockRedisClient.expire).toHaveBeenCalledWith( 141 145 expectedKey, 142 142 - (windowDays + 1) * 24 * 60 * 60, 146 146 + window * 24 * 60 * 60 + 60 * 60, 143 147 ); 144 148 }); 145 149 ··· 153 157 "test-label", 154 158 1640000000000000, 155 159 5, 160 160 + "days", 156 161 ), 157 162 ).rejects.toThrow("Redis down"); 158 163 ··· 160 165 }); 161 166 }); 162 167 168 168 + describe("trackStarterPackForAccount", () => { 169 169 + it("should track starter pack with correct timestamp and TTL", async () => { 170 170 + vi.mocked(mockRedisClient.zRemRangeByScore).mockResolvedValue(0); 171 171 + vi.mocked(mockRedisClient.zAdd).mockResolvedValue(1); 172 172 + vi.mocked(mockRedisClient.expire).mockResolvedValue(true); 173 173 + 174 174 + const timestamp = 1640000000000000; 175 175 + const window = 24; 176 176 + const windowUnit = "hours" as const; 177 177 + 178 178 + await trackStarterPackForAccount( 179 179 + "did:plc:123", 180 180 + "at://did:plc:123/app.bsky.graph.starterpack/abc", 181 181 + timestamp, 182 182 + window, 183 183 + windowUnit, 184 184 + ); 185 185 + 186 186 + const expectedKey = "starterpack:threshold:did:plc:123:24hours"; 187 187 + const windowStartTime = timestamp - window * 60 * 60 * 1000000; 188 188 + 189 189 + expect(mockRedisClient.zRemRangeByScore).toHaveBeenCalledWith( 190 190 + expectedKey, 191 191 + "-inf", 192 192 + windowStartTime, 193 193 + ); 194 194 + expect(mockRedisClient.zAdd).toHaveBeenCalledWith(expectedKey, { 195 195 + score: timestamp, 196 196 + value: "at://did:plc:123/app.bsky.graph.starterpack/abc", 197 197 + }); 198 198 + expect(mockRedisClient.expire).toHaveBeenCalledWith( 199 199 + expectedKey, 200 200 + window * 60 * 60 + 60 * 60, 201 201 + ); 202 202 + }); 203 203 + 204 204 + it("should throw error on Redis failure", async () => { 205 205 + const redisError = new Error("Redis down"); 206 206 + vi.mocked(mockRedisClient.zRemRangeByScore).mockRejectedValue(redisError); 207 207 + 208 208 + await expect( 209 209 + trackStarterPackForAccount( 210 210 + "did:plc:123", 211 211 + "at://did:plc:123/app.bsky.graph.starterpack/abc", 212 212 + 1640000000000000, 213 213 + 24, 214 214 + "hours", 215 215 + ), 216 216 + ).rejects.toThrow("Redis down"); 217 217 + 218 218 + expect(logger.error).toHaveBeenCalled(); 219 219 + }); 220 220 + }); 221 221 + 222 222 + describe("getStarterPackCountInWindow", () => { 223 223 + it("should count starter packs in window", async () => { 224 224 + vi.mocked(mockRedisClient.zCount).mockResolvedValue(3); 225 225 + 226 226 + const currentTime = 1640000000000000; 227 227 + const window = 24; 228 228 + const windowUnit = "hours" as const; 229 229 + const count = await getStarterPackCountInWindow( 230 230 + "did:plc:123", 231 231 + window, 232 232 + windowUnit, 233 233 + currentTime, 234 234 + ); 235 235 + 236 236 + expect(count).toBe(3); 237 237 + const windowStartTime = currentTime - window * 60 * 60 * 1000000; 238 238 + expect(mockRedisClient.zCount).toHaveBeenCalledWith( 239 239 + "starterpack:threshold:did:plc:123:24hours", 240 240 + windowStartTime, 241 241 + "+inf", 242 242 + ); 243 243 + }); 244 244 + 245 245 + it("should throw error on Redis failure", async () => { 246 246 + const redisError = new Error("Redis down"); 247 247 + vi.mocked(mockRedisClient.zCount).mockRejectedValue(redisError); 248 248 + 249 249 + await expect( 250 250 + getStarterPackCountInWindow("did:plc:123", 24, "hours", 1640000000000000), 251 251 + ).rejects.toThrow("Redis down"); 252 252 + 253 253 + expect(logger.error).toHaveBeenCalled(); 254 254 + }); 255 255 + }); 256 256 + 163 257 describe("getPostLabelCountInWindow", () => { 164 258 it("should count posts for single label", async () => { 165 259 vi.mocked(mockRedisClient.zCount).mockResolvedValue(3); 166 260 167 261 const currentTime = 1640000000000000; 168 168 - const windowDays = 5; 262 262 + const window = 5; 263 263 + const windowUnit = "days" as const; 169 264 const count = await getPostLabelCountInWindow( 170 265 "did:plc:123", 171 266 ["test-label"], 172 172 - windowDays, 267 267 + window, 268 268 + windowUnit, 173 269 currentTime, 174 270 ); 175 271 176 272 expect(count).toBe(3); 177 177 - const windowStartTime = currentTime - windowDays * 24 * 60 * 60 * 1000000; 273 273 + const windowStartTime = currentTime - window * 24 * 60 * 60 * 1000000; 178 274 expect(mockRedisClient.zCount).toHaveBeenCalledWith( 179 179 - "account-post-labels:did:plc:123:test-label:5", 275 275 + "account-post-labels:did:plc:123:test-label:5days", 180 276 windowStartTime, 181 277 "+inf", 182 278 ); ··· 189 285 .mockResolvedValueOnce(1); 190 286 191 287 const currentTime = 1640000000000000; 192 192 - const windowDays = 5; 288 288 + const window = 5; 289 289 + const windowUnit = "days" as const; 193 290 const count = await getPostLabelCountInWindow( 194 291 "did:plc:123", 195 292 ["label-1", "label-2", "label-3"], 196 196 - windowDays, 293 293 + window, 294 294 + windowUnit, 197 295 currentTime, 198 296 ); 199 297 ··· 208 306 "did:plc:123", 209 307 ["test-label"], 210 308 5, 309 309 + "days", 211 310 1640000000000000, 212 311 ); 213 312 ··· 223 322 "did:plc:123", 224 323 ["test-label"], 225 324 5, 325 325 + "days", 226 326 1640000000000000, 227 327 ), 228 328 ).rejects.toThrow("Redis down");

+201

src/tests/starterPackThreshold.test.ts

··· 1 1 + import { afterEach, describe, expect, it, vi } from "vitest"; 2 2 + import { 3 3 + createAccountComment, 4 4 + createAccountLabel, 5 5 + createAccountReport, 6 6 + } from "../accountModeration.js"; 7 7 + import { logger } from "../logger.js"; 8 8 + import { 9 9 + starterPackLabelsThresholdAppliedCounter, 10 10 + starterPackThresholdChecksCounter, 11 11 + starterPackThresholdMetCounter, 12 12 + } from "../metrics.js"; 13 13 + import { 14 14 + getStarterPackCountInWindow, 15 15 + trackStarterPackForAccount, 16 16 + } from "../redis.js"; 17 17 + import { 18 18 + checkStarterPackThreshold, 19 19 + loadStarterPackThresholdConfigs, 20 20 + } from "../starterPackThreshold.js"; 21 21 + 22 22 + vi.mock("../logger.js", () => ({ 23 23 + logger: { 24 24 + info: vi.fn(), 25 25 + warn: vi.fn(), 26 26 + error: vi.fn(), 27 27 + debug: vi.fn(), 28 28 + }, 29 29 + })); 30 30 + 31 31 + vi.mock("../../rules/starterPackThreshold.js", () => ({ 32 32 + STARTER_PACK_THRESHOLD_CONFIGS: [ 33 33 + { 34 34 + threshold: 5, 35 35 + window: 24, 36 36 + windowUnit: "hours", 37 37 + accountLabel: "starter-pack-spam", 38 38 + accountComment: "Too many starter packs", 39 39 + toLabel: true, 40 40 + reportAcct: true, 41 41 + commentAcct: false, 42 42 + allowlist: ["did:plc:allowed123"], 43 43 + }, 44 44 + { 45 45 + threshold: 10, 46 46 + window: 7, 47 47 + windowUnit: "days", 48 48 + accountLabel: "starter-pack-abuse", 49 49 + accountComment: "Excessive starter pack creation", 50 50 + toLabel: true, 51 51 + reportAcct: false, 52 52 + commentAcct: true, 53 53 + allowlist: [], 54 54 + }, 55 55 + ], 56 56 + })); 57 57 + 58 58 + vi.mock("../redis.js", () => ({ 59 59 + trackStarterPackForAccount: vi.fn(), 60 60 + getStarterPackCountInWindow: vi.fn(), 61 61 + })); 62 62 + 63 63 + vi.mock("../accountModeration.js", () => ({ 64 64 + createAccountLabel: vi.fn(), 65 65 + createAccountReport: vi.fn(), 66 66 + createAccountComment: vi.fn(), 67 67 + })); 68 68 + 69 69 + vi.mock("../metrics.js", () => ({ 70 70 + starterPackLabelsThresholdAppliedCounter: { 71 71 + inc: vi.fn(), 72 72 + }, 73 73 + starterPackThresholdChecksCounter: { 74 74 + inc: vi.fn(), 75 75 + }, 76 76 + starterPackThresholdMetCounter: { 77 77 + inc: vi.fn(), 78 78 + }, 79 79 + })); 80 80 + 81 81 + describe("Starter Pack Threshold Logic", () => { 82 82 + afterEach(() => { 83 83 + vi.clearAllMocks(); 84 84 + }); 85 85 + 86 86 + describe("loadStarterPackThresholdConfigs", () => { 87 87 + it("should load and cache configs successfully", () => { 88 88 + const configs = loadStarterPackThresholdConfigs(); 89 89 + expect(configs).toHaveLength(2); 90 90 + expect(configs[0].threshold).toBe(5); 91 91 + expect(configs[1].threshold).toBe(10); 92 92 + }); 93 93 + }); 94 94 + 95 95 + describe("checkStarterPackThreshold", () => { 96 96 + const testDid = "did:plc:test123"; 97 97 + const testUri = "at://did:plc:test123/app.bsky.graph.starterpack/abc"; 98 98 + const testTimestamp = 1640000000000000; 99 99 + 100 100 + it("should skip threshold check for allowlisted accounts", async () => { 101 101 + vi.mocked(trackStarterPackForAccount).mockResolvedValue(); 102 102 + vi.mocked(getStarterPackCountInWindow).mockResolvedValue(0); 103 103 + 104 104 + await checkStarterPackThreshold( 105 105 + "did:plc:allowed123", 106 106 + testUri, 107 107 + testTimestamp, 108 108 + ); 109 109 + 110 110 + expect(starterPackThresholdChecksCounter.inc).toHaveBeenCalled(); 111 111 + // Should skip first config (allowlist), but process second config 112 112 + expect(trackStarterPackForAccount).toHaveBeenCalledTimes(1); 113 113 + expect(logger.debug).toHaveBeenCalledWith( 114 114 + expect.objectContaining({ did: "did:plc:allowed123" }), 115 115 + "Account is in allowlist, skipping threshold check", 116 116 + ); 117 117 + }); 118 118 + 119 119 + it("should track and check threshold for non-allowlisted accounts", async () => { 120 120 + vi.mocked(trackStarterPackForAccount).mockResolvedValue(); 121 121 + vi.mocked(getStarterPackCountInWindow).mockResolvedValue(3); 122 122 + 123 123 + await checkStarterPackThreshold(testDid, testUri, testTimestamp); 124 124 + 125 125 + expect(starterPackThresholdChecksCounter.inc).toHaveBeenCalled(); 126 126 + expect(trackStarterPackForAccount).toHaveBeenCalledWith( 127 127 + testDid, 128 128 + testUri, 129 129 + testTimestamp, 130 130 + 24, 131 131 + "hours", 132 132 + ); 133 133 + expect(getStarterPackCountInWindow).toHaveBeenCalledWith( 134 134 + testDid, 135 135 + 24, 136 136 + "hours", 137 137 + testTimestamp, 138 138 + ); 139 139 + }); 140 140 + 141 141 + it("should apply account label when threshold is met", async () => { 142 142 + vi.mocked(trackStarterPackForAccount).mockResolvedValue(); 143 143 + vi.mocked(getStarterPackCountInWindow).mockResolvedValue(5); 144 144 + vi.mocked(createAccountLabel).mockResolvedValue(); 145 145 + vi.mocked(createAccountReport).mockResolvedValue(); 146 146 + 147 147 + await checkStarterPackThreshold(testDid, testUri, testTimestamp); 148 148 + 149 149 + expect(starterPackThresholdMetCounter.inc).toHaveBeenCalledWith({ 150 150 + account_label: "starter-pack-spam", 151 151 + }); 152 152 + expect(createAccountLabel).toHaveBeenCalledWith( 153 153 + testDid, 154 154 + "starter-pack-spam", 155 155 + expect.stringContaining("Too many starter packs"), 156 156 + ); 157 157 + expect(createAccountReport).toHaveBeenCalled(); 158 158 + expect(starterPackLabelsThresholdAppliedCounter.inc).toHaveBeenCalledWith({ 159 159 + account_label: "starter-pack-spam", 160 160 + action: "label", 161 161 + }); 162 162 + }); 163 163 + 164 164 + it("should not apply label when threshold not met", async () => { 165 165 + vi.mocked(trackStarterPackForAccount).mockResolvedValue(); 166 166 + vi.mocked(getStarterPackCountInWindow).mockResolvedValue(3); 167 167 + 168 168 + await checkStarterPackThreshold(testDid, testUri, testTimestamp); 169 169 + 170 170 + expect(starterPackThresholdMetCounter.inc).not.toHaveBeenCalled(); 171 171 + expect(createAccountLabel).not.toHaveBeenCalled(); 172 172 + }); 173 173 + 174 174 + it("should handle Redis errors", async () => { 175 175 + const redisError = new Error("Redis connection failed"); 176 176 + vi.mocked(trackStarterPackForAccount).mockRejectedValue(redisError); 177 177 + 178 178 + await expect( 179 179 + checkStarterPackThreshold(testDid, testUri, testTimestamp), 180 180 + ).rejects.toThrow("Redis connection failed"); 181 181 + 182 182 + expect(logger.error).toHaveBeenCalled(); 183 183 + }); 184 184 + 185 185 + it("should check all configs for each starter pack", async () => { 186 186 + vi.mocked(trackStarterPackForAccount).mockResolvedValue(); 187 187 + vi.mocked(getStarterPackCountInWindow) 188 188 + .mockResolvedValueOnce(5) 189 189 + .mockResolvedValueOnce(10); 190 190 + vi.mocked(createAccountLabel).mockResolvedValue(); 191 191 + vi.mocked(createAccountReport).mockResolvedValue(); 192 192 + vi.mocked(createAccountComment).mockResolvedValue(); 193 193 + 194 194 + await checkStarterPackThreshold(testDid, testUri, testTimestamp); 195 195 + 196 196 + expect(trackStarterPackForAccount).toHaveBeenCalledTimes(2); 197 197 + expect(getStarterPackCountInWindow).toHaveBeenCalledTimes(2); 198 198 + expect(createAccountLabel).toHaveBeenCalledTimes(2); 199 199 + }); 200 200 + }); 201 201 + });

+28 -1

src/types.ts

··· 3 3 export interface Checks { 4 4 language?: string[]; 5 5 label: string; 6 6 + unlabel?: boolean; 6 7 comment: string; 7 8 description?: boolean; 8 9 displayName?: boolean; ··· 10 11 commentAcct: boolean; 11 12 reportPost?: boolean; 12 13 toLabel: boolean; 14 14 + trackOnly?: boolean; 13 15 duration?: number; 14 16 check: RegExp; 15 17 whitelist?: RegExp; ··· 62 64 expires?: string; // Optional expiration date (ISO 8601) - check will be skipped after this date 63 65 } 64 66 67 67 + export type WindowUnit = "minutes" | "hours" | "days"; 68 68 + 65 69 export interface AccountThresholdConfig { 66 70 labels: string | string[]; // Single label or array for OR matching 67 71 threshold: number; // Number of labeled posts required to trigger account action 68 72 accountLabel: string; // Label to apply to the account 69 73 accountComment: string; // Comment for the account action 70 70 - windowDays: number; // Rolling window in days 74 74 + window: number; // Rolling window duration 75 75 + windowUnit: WindowUnit; // Unit for the rolling window 71 76 reportAcct: boolean; // Whether to report the account 72 77 commentAcct: boolean; // Whether to comment on the account 73 78 toLabel?: boolean; // Whether to apply label (defaults to true) 74 79 } 80 80 + 81 81 + export interface StarterPackThresholdConfig { 82 82 + threshold: number; 83 83 + window: number; 84 84 + windowUnit: WindowUnit; 85 85 + accountLabel: string; 86 86 + accountComment: string; 87 87 + toLabel?: boolean; 88 88 + reportAcct?: boolean; 89 89 + commentAcct?: boolean; 90 90 + allowlist?: string[]; 91 91 + } 92 92 + 93 93 + export interface ModerationError { 94 94 + action: "label" | "report" | "comment" | "unlabel"; 95 95 + error: unknown; 96 96 + } 97 97 + 98 98 + export interface ModerationResult { 99 99 + success: boolean; 100 100 + errors: ModerationError[]; 101 101 + }