@atcute/bluesky-moderation 1.0.1

package/lib/subjects/post.ts

@@ -0,0 +1,316 @@
+import { unwrapEmbed, unwrapRecordEmbed } from '@atcute/bluesky';
+import type {
+	AppBskyActorDefs,
+	AppBskyFeedDefs,
+	AppBskyFeedPost,
+	AppBskyGraphStarterpack,
+	At,
+} from '@atcute/client/lexicons';
+
+import { LabelTarget } from '../behaviors.js';
+import {
+	considerBlockedBy,
+	considerBlocking,
+	considerHidden,
+	considerKeywordMute,
+	considerLabels,
+	createModerationDecision,
+	downgradeDecision,
+	mergeModerationDecisions,
+	type ModerationDecision,
+} from '../decision.js';
+import type { ModerationOptions, PostSubject } from '../types.js';
+
+import { matchesKeywordFilters } from '../internal/keyword-filter.js';
+import type { KeywordFilter } from '../keyword-filter.js';
+
+import { moderateProfile } from './profile.js';
+
+export const moderatePost = (subject: PostSubject, opts: ModerationOptions) => {
+	return mergeModerationDecisions(
+		decideSubject(subject, opts),
+		moderateProfile(subject.author, opts),
+		downgradeDecision(decideEmbed(subject.embed, opts)),
+	);
+};
+
+const decideSubject = (subject: PostSubject, opts: ModerationOptions): ModerationDecision => {
+	const author = subject.author;
+
+	const decision = createModerationDecision(author.did, opts);
+	considerLabels(decision, LabelTarget.Content, subject.labels, opts);
+
+	if (checkHiddenPost(subject, opts.prefs.hiddenPosts)) {
+		considerHidden(decision);
+	}
+
+	if (!decision.isMe && opts.prefs.keywordFilters?.length) {
+		const match = checkKeywordFilters(subject, opts.prefs.keywordFilters);
+		if (match !== null) {
+			considerKeywordMute(decision, match);
+		}
+	}
+
+	return decision;
+};
+
+const decideEmbed = (
+	embed: AppBskyFeedDefs.PostView['embed'],
+	opts: ModerationOptions,
+): ModerationDecision | undefined => {
+	const link = unwrapRecordEmbed(embed);
+
+	if (link) {
+		switch (link.$type) {
+			case 'app.bsky.embed.record#viewRecord': {
+				const author = link.author;
+
+				const decision = createModerationDecision(author.did, opts);
+				considerLabels(decision, LabelTarget.Content, link.labels, opts);
+
+				return mergeModerationDecisions(decision, moderateProfile(author, opts));
+			}
+			case 'app.bsky.embed.record#viewBlocked': {
+				const author = link.author;
+				const viewer = author.viewer;
+
+				const decision = createModerationDecision(author.did, opts);
+
+				if (viewer?.blocking) {
+					considerBlocking(decision, viewer.blockingByList ?? null);
+				}
+
+				if (viewer?.blockedBy) {
+					considerBlockedBy(decision);
+				}
+
+				return decision;
+			}
+		}
+	}
+};
+
+const checkHiddenPost = (
+	subject: PostSubject,
+	hiddenPosts: At.CanonicalResourceUri[] | undefined,
+): boolean => {
+	if (!hiddenPosts?.length) {
+		return false;
+	}
+
+	if (hiddenPosts.includes(subject.uri as At.CanonicalResourceUri)) {
+		return true;
+	}
+
+	const record = unwrapRecordEmbed(subject.embed);
+	if (record) {
+		switch (record.$type) {
+			case 'app.bsky.embed.record#viewBlocked':
+			case 'app.bsky.embed.record#viewDetached':
+			case 'app.bsky.embed.record#viewNotFound':
+			case 'app.bsky.embed.record#viewRecord': {
+				return hiddenPosts.includes(subject.uri as At.CanonicalResourceUri);
+			}
+		}
+	}
+
+	return false;
+};
+
+const checkKeywordFilters = (
+	subject: PostSubject,
+	filters: KeywordFilter[] | undefined,
+): KeywordFilter | null => {
+	if (!filters?.length) {
+		return null;
+	}
+
+	let match: KeywordFilter | null | undefined;
+
+	const author = subject.author;
+
+	{
+		const record = subject.record as AppBskyFeedPost.Record;
+
+		const tags: string[] = [
+			...(record.tags ?? []),
+			...(record.facets ?? []).flatMap((facet) => {
+				return facet.features
+					.filter((feature) => feature.$type === 'app.bsky.richtext.facet#tag')
+					.map((feature) => feature.tag);
+			}),
+		];
+
+		if (
+			(match = matchesKeywordFilters({
+				filters: filters,
+				text: record.text,
+				tags: tags,
+				actor: author,
+			}))
+		) {
+			return match;
+		}
+	}
+
+	{
+		const embed = subject.embed;
+
+		if ((match = checkEmbedKeywordFilters(filters, embed, author))) {
+			return match;
+		}
+	}
+
+	return null;
+};
+
+const checkEmbedKeywordFilters = (
+	filters: KeywordFilter[],
+	embed: AppBskyFeedDefs.PostView['embed'],
+	author: AppBskyActorDefs.ProfileViewBasic,
+): KeywordFilter | null => {
+	let match: KeywordFilter | null | undefined;
+
+	const { media, record: link } = unwrapEmbed(embed);
+
+	if (media) {
+		switch (media.$type) {
+			case 'app.bsky.embed.external#view': {
+				const external = media.external;
+
+				if (
+					(match = matchesKeywordFilters({
+						filters: filters,
+						text: `${external.title} ${external.description}`,
+						actor: author,
+					}))
+				) {
+					return match;
+				}
+
+				break;
+			}
+			case 'app.bsky.embed.images#view': {
+				const images = media.images;
+
+				for (let i = 0, il = images.length; i < il; i++) {
+					const image = images[i];
+					if (!image.alt) {
+						continue;
+					}
+
+					if (
+						(match = matchesKeywordFilters({
+							filters: filters,
+							text: image.alt,
+							actor: author,
+						}))
+					) {
+						return match;
+					}
+				}
+
+				break;
+			}
+			case 'app.bsky.embed.video#view': {
+				if (!media.alt) {
+					break;
+				}
+
+				if (
+					(match = matchesKeywordFilters({
+						filters: filters,
+						text: media.alt,
+						actor: author,
+					}))
+				) {
+					return match;
+				}
+			}
+		}
+	}
+
+	if (link) {
+		switch (link.$type) {
+			case 'app.bsky.embed.record#viewRecord': {
+				{
+					const author = link.author;
+					const record = link.value as AppBskyFeedPost.Record;
+
+					const tags: string[] = [
+						...(record.tags ?? []),
+						...(record.facets ?? []).flatMap((facet) => {
+							return facet.features
+								.filter((feature) => feature.$type === 'app.bsky.richtext.facet#tag')
+								.map((feature) => feature.tag);
+						}),
+					];
+
+					if (
+						(match = matchesKeywordFilters({
+							filters: filters,
+							text: record.text,
+							tags: tags,
+							actor: author,
+						}))
+					) {
+						return match;
+					}
+				}
+
+				{
+					const embed = link.embeds?.[0];
+
+					if ((match = checkEmbedKeywordFilters(filters, embed, author))) {
+						return match;
+					}
+				}
+
+				break;
+			}
+			case 'app.bsky.feed.defs#generatorView': {
+				if (
+					(match = matchesKeywordFilters({
+						filters: filters,
+						text: `${link.displayName} ${link.description ?? ''}`,
+						actor: link.creator,
+					}))
+				) {
+					return match;
+				}
+
+				break;
+			}
+			case 'app.bsky.graph.defs#listView': {
+				if (
+					(match = matchesKeywordFilters({
+						filters: filters,
+						text: `${link.name} ${link.description ?? ''}`,
+						actor: link.creator,
+					}))
+				) {
+					return match;
+				}
+
+				break;
+			}
+			case 'app.bsky.graph.defs#starterPackViewBasic': {
+				const record = link.record as AppBskyGraphStarterpack.Record;
+
+				if (
+					(match = matchesKeywordFilters({
+						filters: filters,
+						text: `${record.name} ${record.description ?? ''}`,
+						actor: link.creator,
+					}))
+				) {
+					return match;
+				}
+
+				break;
+			}
+		}
+	}
+
+	return null;
+};

package/lib/subjects/profile.ts

@@ -0,0 +1,42 @@
+import { LabelTarget } from '../behaviors.js';
+import {
+	considerBlockedBy,
+	considerBlocking,
+	considerLabel,
+	considerPermanentMute,
+	createModerationDecision,
+	type ModerationDecision,
+} from '../decision.js';
+import type { ModerationOptions, ProfileSubject } from '../types.js';
+
+export const moderateProfile = (subject: ProfileSubject, opts: ModerationOptions): ModerationDecision => {
+	const decision = createModerationDecision(subject.did, opts);
+
+	const viewer = subject.viewer;
+	if (viewer) {
+		if (viewer.muted) {
+			considerPermanentMute(decision, viewer.mutedByList ?? null);
+		}
+
+		if (viewer.blocking) {
+			considerBlocking(decision, viewer.blockingByList ?? null);
+		}
+
+		if (viewer.blockedBy) {
+			considerBlockedBy(decision);
+		}
+	}
+
+	if (subject.labels?.length) {
+		for (const label of subject.labels) {
+			const target =
+				!label.uri.endsWith('/app.bsky.actor.profile/self') || label.val === '!no-unauthenticated'
+					? LabelTarget.Account
+					: LabelTarget.Profile;
+
+			considerLabel(decision, target, label, opts);
+		}
+	}
+
+	return decision;
+};

package/lib/types.ts

@@ -0,0 +1,61 @@
+import type {
+	AppBskyActorDefs,
+	AppBskyFeedDefs,
+	AppBskyGraphDefs,
+	AppBskyNotificationListNotifications,
+	At,
+	ChatBskyActorDefs,
+	ComAtprotoLabelDefs,
+} from '@atcute/client/lexicons';
+
+import type { KeywordFilter } from './keyword-filter.js';
+import type { InterpretedLabelMapping, LabelPreference } from './label.js';
+
+export type Label = ComAtprotoLabelDefs.Label;
+
+export interface LabelerPreference {
+	/** preferences for labels issued by this labeler */
+	labelPrefs: Record<string, LabelPreference | undefined>;
+}
+
+export interface ModerationPreferences {
+	/** whether adult content is allowed to be shown */
+	adultContentEnabled?: boolean;
+
+	/** preferences for global-defined labels */
+	globalLabelPrefs?: Record<string, LabelPreference | undefined>;
+	/** preferences for labelers */
+	prefsByLabelers?: { [D in At.Did]?: LabelerPreference };
+
+	/** list of hidden posts */
+	hiddenPosts?: At.CanonicalResourceUri[];
+	/** list of temporarily muted users */
+	temporaryMutes?: At.Did[];
+
+	/** list of keyword filters */
+	keywordFilters?: KeywordFilter[];
+}
+
+export interface ModerationOptions {
+	/** DID of the viewer */
+	viewerDid: At.Did | undefined;
+	/** moderation preferences */
+	prefs: ModerationPreferences;
+
+	/** interpreted label definitions from labelers */
+	labelDefs?: { [D in At.Did]?: InterpretedLabelMapping };
+}
+
+export type FeedGeneratorSubject = AppBskyFeedDefs.GeneratorView;
+
+export type ListSubject = AppBskyGraphDefs.ListView | AppBskyGraphDefs.ListViewBasic;
+
+export type NotificationSubject = AppBskyNotificationListNotifications.Notification;
+
+export type PostSubject = AppBskyFeedDefs.PostView;
+
+export type ProfileSubject =
+	| AppBskyActorDefs.ProfileViewBasic
+	| AppBskyActorDefs.ProfileView
+	| AppBskyActorDefs.ProfileViewDetailed
+	| ChatBskyActorDefs.ProfileViewBasic;

package/lib/ui.ts

@@ -0,0 +1,183 @@
+import {
+	BLOCK_BEHAVIOR,
+	DisplayContext,
+	HIDE_BEHAVIOR,
+	KEYWORD_MUTE_BEHAVIOR,
+	LabelTarget,
+	ModerationAction,
+	MUTE_BEHAVIOR,
+} from './behaviors.js';
+import { ModerationCauseType, type ModerationCause, type ModerationDecision } from './decision.js';
+import { LabelPreference } from './label.js';
+
+export interface DisplayRestrictions {
+	noOverride: boolean;
+	filters: ModerationCause[];
+	blurs: ModerationCause[];
+	alerts: ModerationCause[];
+	informs: ModerationCause[];
+}
+
+export const getDisplayRestrictions = (
+	decision: ModerationDecision,
+	context: DisplayContext,
+): DisplayRestrictions => {
+	const filters: ModerationCause[] = [];
+	const blurs: ModerationCause[] = [];
+	const alerts: ModerationCause[] = [];
+	const informs: ModerationCause[] = [];
+
+	let noOverride: boolean = false;
+
+	for (const cause of decision.causes) {
+		switch (cause.type) {
+			case ModerationCauseType.Label: {
+				if (cause.pref === LabelPreference.Hide && !decision.isMe) {
+					if (context === DisplayContext.ProfileList && cause.target == LabelTarget.Account) {
+						filters.push(cause);
+					} else if (
+						context === DisplayContext.ContentList &&
+						(cause.target === LabelTarget.Account || cause.target === LabelTarget.Content)
+					) {
+						filters.push(cause);
+					}
+				}
+
+				if (!cause.downgraded) {
+					switch (cause.behavior[context]) {
+						case ModerationAction.Blur: {
+							noOverride ||= cause.noOverride && !decision.isMe;
+							blurs.push(cause);
+							break;
+						}
+						case ModerationAction.Alert: {
+							alerts.push(cause);
+							break;
+						}
+						case ModerationAction.Inform: {
+							informs.push(cause);
+							break;
+						}
+					}
+				}
+
+				break;
+			}
+
+			case ModerationCauseType.MutedPermanent:
+			case ModerationCauseType.MutedTemporary: {
+				if (context === DisplayContext.ProfileList || context === DisplayContext.ContentList) {
+					filters.push(cause);
+				}
+
+				if (!cause.downgraded) {
+					switch (MUTE_BEHAVIOR[context]) {
+						case ModerationAction.Blur: {
+							blurs.push(cause);
+							break;
+						}
+						case ModerationAction.Alert: {
+							alerts.push(cause);
+							break;
+						}
+						case ModerationAction.Inform: {
+							informs.push(cause);
+							break;
+						}
+					}
+				}
+
+				break;
+			}
+
+			case ModerationCauseType.MutedKeyword: {
+				if (context === DisplayContext.ContentList) {
+					filters.push(cause);
+				}
+
+				if (!cause.downgraded) {
+					switch (KEYWORD_MUTE_BEHAVIOR[context]) {
+						case ModerationAction.Blur: {
+							blurs.push(cause);
+							break;
+						}
+						case ModerationAction.Alert: {
+							alerts.push(cause);
+							break;
+						}
+						case ModerationAction.Inform: {
+							informs.push(cause);
+							break;
+						}
+					}
+				}
+
+				break;
+			}
+
+			case ModerationCauseType.Hidden: {
+				if (context === DisplayContext.ProfileList || context === DisplayContext.ContentList) {
+					filters.push(cause);
+				}
+
+				if (!cause.downgraded) {
+					switch (HIDE_BEHAVIOR[context]) {
+						case ModerationAction.Blur: {
+							blurs.push(cause);
+							break;
+						}
+						case ModerationAction.Alert: {
+							alerts.push(cause);
+							break;
+						}
+						case ModerationAction.Inform: {
+							informs.push(cause);
+							break;
+						}
+					}
+				}
+
+				break;
+			}
+
+			case ModerationCauseType.BlockedBy:
+			case ModerationCauseType.Blocking: {
+				if (context === DisplayContext.ProfileList || context === DisplayContext.ContentList) {
+					filters.push(cause);
+				}
+
+				if (!cause.downgraded) {
+					switch (BLOCK_BEHAVIOR[context]) {
+						case ModerationAction.Blur: {
+							noOverride = true;
+							blurs.push(cause);
+							break;
+						}
+						case ModerationAction.Alert: {
+							alerts.push(cause);
+							break;
+						}
+						case ModerationAction.Inform: {
+							informs.push(cause);
+							break;
+						}
+					}
+				}
+
+				break;
+			}
+		}
+	}
+
+	return {
+		noOverride,
+		filters: filters.sort(sortByPriority),
+		blurs: blurs.sort(sortByPriority),
+		alerts: alerts.sort(sortByPriority),
+		informs: informs.sort(sortByPriority),
+	};
+};
+
+const sortByPriority = (a: ModerationCause, b: ModerationCause) => {
+	return a.priority - b.priority;
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "type": "module",
+  "name": "@atcute/bluesky-moderation",
+  "version": "1.0.1",
+  "description": "interprets Bluesky's content moderation labels",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/bluesky/moderation"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@atcute/bluesky": "^2.0.0",
+    "@atcute/client": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.1",
+    "vitest": "^3.0.4",
+    "@atcute/bluesky": "^2.0.3",
+    "@atcute/client": "^3.0.1"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "vitest",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}