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.

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.

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

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.

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);

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 }],

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

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.

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.

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.

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.

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.

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