strfry policies

A collection of policies for the strfry Nostr relay, built in Deno.

For more information about policy plugins, see strfry: Write policy plugins.

This library introduces a model for writing policies and composing them in a pipeline. Policies are fully configurable and it's easy to add your own or install more from anywhere on the net.

Getting started

To get up and running, you will need to install Deno on the same machine as strfry:

sudo apt install -y unzip
curl -fsSL https://deno.land/x/install/install.sh | sudo DENO_INSTALL=/usr/local sh

Create an entrypoint file somewhere and make it executable:

sudo touch /opt/strfry-policy.ts
sudo chmod +x /opt/strfry-policy.ts

Now you can write your policy. Here's a good starting point:

#!/bin/sh
//bin/true; exec deno run -A "$0" "$@"
import {
  antiDuplicationPolicy,
  hellthreadPolicy,
  pipeline,
  rateLimitPolicy,
  readStdin,
  writeStdout,
} from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';

for await (const msg of readStdin()) {
  const result = await pipeline(msg, [
    [hellthreadPolicy, { limit: 100 }],
    [antiDuplicationPolicy, { ttl: 60000, minLength: 50 }],
    [rateLimitPolicy, { whitelist: ['127.0.0.1'] }],
  ]);

  writeStdout(result);
}

Finally, edit strfry.conf and enable the policy:

     writePolicy {
         # If non-empty, path to an executable script that implements the writePolicy plugin logic
-        plugin = ""
+        plugin = "/opt/strfry-policy.ts"
 
         # Number of seconds to search backwards for lookback events when starting the writePolicy plugin (0 for no lookback)
         lookbackSeconds = 0

That's it! 🎉 Now you should check strfry logs to ensure everything is working okay.

Available policies

For complete documentation of policies, see: https://doc.deno.land/https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts

Policy	Description	Example Options
antiDuplicationPolicy	Prevent messages with the exact same content from being submitted repeatedly.	{ ttl: 60000, minLength: 50}
filterPolicy	Reject all events which don't match the filter.	{ kinds: [0, 1, 3, 5, 6, 7] }
hellthreadPolicy	Reject messages that tag too many participants.	{ limit: 15 }
keywordPolicy	Reject events containing any of the strings in its content.	['moo', 'oink', 'honk']
noopPolicy	Minimal sample policy for demonstration purposes. Allows all events through.
openaiPolicy	Passes event content to OpenAI and then rejects flagged events.	{ apiKey: '123...' }
powPolicy	Reject events which don't meet Proof-of-Work (NIP-13) criteria.	{ difficulty: 20 }
pubkeyBanPolicy	Ban individual pubkeys from publishing events to the relay.	['e810...', 'fafa...', '1e89...']
rateLimitPolicy	Rate-limits users by their IP address.	{ max: 10, interval: 60000 }
readOnlyPolicy	This policy rejects all messages.
regexPolicy	Reject events whose content matches the regex.	/(🟠|🔥|😳)ChtaGPT/i
whitelistPolicy	Allows only the listed pubkeys to post to the relay. All other events are rejected.	['e810...', 'fafa...', '1e89...']

Upgrading strfry-policies

When writing your script, it's a good idea to import the module with a permalink, eg:

- import * as strfry from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';
+ import * as strfry from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/33ef127ca7599d9d7016786cbe2de34c9536078c/mod.ts';

You can also import from a tag:

- import * as strfry from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';
+ import * as strfry from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/v0.1.0/mod.ts';

Therefore, to upgrade to a newer version of strfry-policies, you can simply change the import URL.

Writing your own policies

You can write a policy in TypeScript and host it anywhere. Deno allows importing modules by URL, making it easy to share policies.

Here is a basic sample policy:

import type { Policy } from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';

/** Only American English is allowed. */
const americanPolicy: Policy<void> = (msg) => {
  const { content } = msg.event;

  const words = [
    'armour',
    'behaviour',
    'colour',
    'favourite',
    'flavour',
    'honour',
    'humour',
    'rumour',
  ];

  const isBritish = words.some((word) => content.toLowerCase().includes(word));

  if (isBritish) {
    return {
      id: msg.event.id,
      action: 'reject',
      msg: 'Sorry, only American English is allowed on this server!',
    };
  } else {
    return {
      id: msg.event.id,
      action: 'accept',
      msg: '',
    };
  }
};

export default americanPolicy;

Once you're done, you can either upload the file somewhere online or directly to your server. Then, update your pipeline:

--- a/strfry-policy.ts
+++ b/strfry-policy.ts
@@ -8,12 +8,14 @@ import {
   readStdin,
   writeStdout,
 } from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';
+import { americanPolicy } from 'https://gist.githubusercontent.com/alexgleason/5c2d084434fa0875397f44da198f4352/raw/3d3ce71c7ed9cef726f17c3a102c378b81760a45/american-policy.ts';
 
 for await (const msg of readStdin()) {
   const result = await pipeline(msg, [
     [hellthreadPolicy, { limit: 100 }],
     [antiDuplicationPolicy, { ttl: 60000, minLength: 50 }],
     [rateLimitPolicy, { whitelist: ['127.0.0.1'] }],
+    americanPolicy,
   ]);
 
   writeStdout(result);

Policy options

The Policy<Opts> type is a generic that accepts options of any type. With opts, the policy above could be rewritten as:

--- a/american-policy.ts
+++ b/american-policy.ts
@@ -1,7 +1,11 @@
 import type { Policy } from 'https://gitlab.com/soapbox-pub/strfry-policies/-/raw/develop/mod.ts';
 
+interface American {
+  withGrey?: boolean;
+}
+
 /** Only American English is allowed. */
-const americanPolicy: Policy<void> = (msg) => {
+const americanPolicy: Policy<American> = (msg, opts) => {
   const { content } = msg.event;
 
   const words = [
@@ -15,6 +19,10 @@
     'rumour',
   ];
 
+  if (opts?.withGrey) {
+    words.push('grey');
+  }
+
   const isBritish = words.some((word) => content.toLowerCase().includes(word));
 
   if (isBritish) {

Then, in the pipeline:

-  americanPolicy,
+  [americanPolicy, { withGrey: true }],

Caveats

• You should not use console.log anywhere in your policies, as strfry expects stdout to be the strfry output message.

Usage with Node.js

We highly recommend running this library with Deno, but for those looking to incorporate it into an existing Node.js project, an NPM version is provided:

• https://www.npmjs.com/package/strfry-policies

This version is built with dnt which provides Node.js shims for Deno features. Some policies that rely on sqlite may not work, but core fuctionality and TypeScript types work fine, so it can be used as a framework to build other policies.

Filtering jsonl events with your policy

It is not currently possible to retroactively filter events on your strfry relay. You can however export the events with strfry export, filter them locally, and then import them into a fresh database. You can also use this command to filter Nostr events from any source, not just strfry.

To do so, run:

cat [EVENTS_FILE] | deno task filter [POLICY_CMD] > [OUT_FILE]

For example:

cat events.jsonl | deno task filter ./my-policy.ts > filtered.jsonl

Accepted messages will be written to stdout, while rejected messages will be skipped. Also, [POLICY_CMD] can be any strfry policy, not just one created from this repo.

The command wraps each event in a strfry message of type new, with an IP4 source of 127.0.0.1, and a timestamp of the current UTC time. Therefore you may want to avoid certain policies such as the rateLimitPolicy that don't makes sense in this context.

FAQ

Why Deno?

Deno was developed by the creator of Node.js to solve various problems with Node. It implements web standard APIs such as SubtleCrypto and Fetch so your code is compatible with web browsers. It is also significantly faster in benchmarks.

Can I integrate this into another project?

If you're building your own relay, make it compatible with strfry plugins. strfry plugins utilize stdin and stdout of the operating system, so the relay can be written in any programming language and it will be able to utilize plugins written in any programming language.

If you're writing software that deals with Nostr events in JavaScript or TypeScript, you can import this library and use its functions directly.

Is performance good?

It depends on which policies you use, but the short answer is "yes." Even policies that rely on sqlite (such as rateLimitPolicy and antiDuplicationPolicy) perform well. You should place those policies at the end of your pipeline so that synchronous policies have the chance to reject sooner. You can also mount a tmpfs volume and pass a databaseUrl option into those policies to serve their database from memory.

License

This is free and unencumbered software released into the public domain.