R9 Web Push, then the honest version: VAPID key, push subscriptions, encrypted pushes, 4.5.0 advertised

The server's VAPID key (PushKeys, made on first need, in Mongo) is the instance API's vapid.public_key and every app's
vapid_key. /api/v1/push/subscription (POST, GET, PUT, DELETE) keeps one subscription per access token, so per persona;
every notification kept (never a filtered one) is queued as a SendPush job for the subscriptions whose alert and policy
admit it, and sent through the `push` client (the safe handler, https only) encrypted as RFC 8291 aes128gcm or the
aesgcm draft with an ES256 VAPID JWT. 404/410 delete the subscription, 429/5xx/timeouts retry, other answers drop the
push. Subscriptions end with their tokens (revocation, sessions ended, suspension, deletion, a restore); backups hold
neither keys nor subscriptions. The walk of every Mastodon 4.3-4.5 client route (docs/MASTODON-API.md) added
conversations/:id/unread, domain_blocks/preview, v2 notifications clear and PUT policy, /oauth/userinfo and stubs, so both
instance APIs now say 4.5.0 (compatible; PrivaPub <release>). The pasture gets a push sink (pushsink.test) and
scenarios/push.sh in batch A.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WpVCoDeM1qUTRp4fXQdfof

PrivaPub/Infrastructure/Push/Vapid.cs

@@ -0,0 +1,116 @@
+using MongoDB.Driver;
+using MongoDB.Entities;
+
+using PrivaPub.Models;
+
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace PrivaPub.Infrastructure.Push
+{
+	// The server's VAPID key (RFC 8292, completion program R9) and the JWT every push carries. The key is made the first time
+	// it is needed and kept in Mongo (PushKeys, one document); every process reads that one.
+	public interface IVapid
+	{
+		Task<VapidKey> Key(CancellationToken token);
+	}
+
+	public sealed class VapidKey
+	{
+		// RFC 8292 2: no more than 24 hours ahead; half of it leaves room for a push service's clock
+		public static readonly TimeSpan TokenLifetime = TimeSpan.FromHours(12);
+
+		readonly ECParameters _parameters;
+
+		public VapidKey(byte[] publicPoint, byte[] d)
+		{
+			PublicPoint = publicPoint;
+			_parameters = new ECParameters
+			{
+				Curve = ECCurve.NamedCurves.nistP256,
+				D = d,
+				Q = new ECPoint { X = publicPoint[1..33], Y = publicPoint[33..] }
+			};
+		}
+
+		public byte[] PublicPoint { get; }
+
+		/// <summary>As the APIs give it (the instance's vapid.public_key, an app's vapid_key, a subscription's server_key):
+		/// URL-safe base64 with its padding, as Mastodon's VAPID_PUBLIC_KEY is written.</summary>
+		public string ForApi => Convert.ToBase64String(PublicPoint).Replace('+', '-').Replace('/', '_');
+
+		/// <summary>As headers take it (RFC 8292's k, the draft's Crypto-Key p256ecdsa): base64url without padding.</summary>
+		public string ForHeader => WebPushCrypto.Base64Url(PublicPoint);
+
+		/// <summary>The ES256 JWT for one push service (aud: its origin), signed by this key.</summary>
+		public string Token(string audience, string subject, DateTime now)
+		{
+			var header = WebPushCrypto.Base64Url("{\"typ\":\"JWT\",\"alg\":\"ES256\"}"u8);
+			var claims = WebPushCrypto.Base64Url(JsonSerializer.SerializeToUtf8Bytes(new Dictionary<string, object>
+			{
+				["aud"] = audience,
+				["exp"] = new DateTimeOffset(now + TokenLifetime).ToUnixTimeSeconds(),
+				["sub"] = subject
+			}));
+			var signed = header + "." + claims;
+			using var key = ECDsa.Create(_parameters);
+			var signature = key.SignData(Encoding.ASCII.GetBytes(signed), HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation);
+			return signed + "." + WebPushCrypto.Base64Url(signature);
+		}
+
+		/// <summary>A push service's origin, the JWT's aud: scheme, host and a port that is not the scheme's own.</summary>
+		public static string Audience(Uri endpoint) => endpoint.GetLeftPart(UriPartial.Authority).ToLower(CultureInfo.InvariantCulture);
+	}
+
+	public class Vapid : IVapid
+	{
+		readonly SemaphoreSlim _gate = new(1, 1);
+		volatile VapidKey _key;
+
+		public async Task<VapidKey> Key(CancellationToken token)
+		{
+			if (_key is { } known)
+				return known;
+			await _gate.WaitAsync(token);
+			try
+			{
+				if (_key is { } meanwhile)
+					return meanwhile;
+				var stored = await Stored(token) ?? await Make(token);
+				_key = new VapidKey(WebPushCrypto.FromBase64Url(stored.PublicKey), WebPushCrypto.FromBase64Url(stored.PrivateKey));
+				return _key;
+			}
+			finally
+			{
+				_gate.Release();
+			}
+		}
+
+		static Task<PushKeys> Stored(CancellationToken token) =>
+			DB.Default.Find<PushKeys>().Match(k => k.ID == PushKeys.Name).ExecuteFirstAsync(token);
+
+		// the first need makes it; two processes at once keep the first one saved
+		static async Task<PushKeys> Make(CancellationToken token)
+		{
+			using var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+			var parameters = key.ExportParameters(true);
+			var keys = new PushKeys
+			{
+				ID = PushKeys.Name,
+				PublicKey = WebPushCrypto.Base64Url([0x04, .. parameters.Q.X, .. parameters.Q.Y]),
+				PrivateKey = WebPushCrypto.Base64Url(parameters.D)
+			};
+			try
+			{
+				await DB.Default.InsertAsync(keys, token);
+				return keys;
+			}
+			catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey)
+			{
+				return await Stored(token);
+			}
+		}
+	}
+}

PrivaPub/Infrastructure/Push/WebPushCrypto.cs

@@ -0,0 +1,169 @@
+using System.Buffers.Binary;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace PrivaPub.Infrastructure.Push
+{
+	// Web Push message encryption, on System.Security.Cryptography alone (completion program R9). Two encodings, as Mastodon
+	// sends them:
+	// - RFC 8291 (`aes128gcm`, in RFC 8188's record), for a subscription made with `standard` (Mastodon 4.4);
+	// - the draft before it (`aesgcm`: draft-ietf-webpush-encryption-04 over draft-ietf-httpbis-encryption-encoding-03), for
+	//   every other one, with its salt in the Encryption header and our public key in Crypto-Key.
+	// Both: a fresh P-256 key pair and a fresh 16-byte salt per message, ECDH with the client's p256dh, HKDF-SHA-256 keyed by
+	// its auth secret, AES-128-GCM, one record. Only the client can read the message; the push service carries it blind.
+	public static class WebPushCrypto
+	{
+		public const int RecordSize = 4096;
+		// the largest payload a 4096-byte aes128gcm body holds: 86 bytes of header, the delimiter and the tag
+		public const int MaxPayload = RecordSize - 86 - 1 - 16;
+		const int SaltLength = 16;
+		const int TagLength = 16;
+
+		public sealed record Message(byte[] Body, string ContentEncoding, byte[] Salt, byte[] ServerPublicKey);
+
+		public static Message Aes128Gcm(ReadOnlySpan<byte> plaintext, byte[] clientPublicKey, byte[] authSecret)
+		{
+			using var server = ECDiffieHellman.Create(ECCurve.NamedCurves.nistP256);
+			return Aes128Gcm(plaintext, clientPublicKey, authSecret, server, RandomNumberGenerator.GetBytes(SaltLength));
+		}
+
+		public static Message Aes128Gcm(ReadOnlySpan<byte> plaintext, byte[] clientPublicKey, byte[] authSecret, ECDiffieHellman server, byte[] salt)
+		{
+			if (plaintext.Length > MaxPayload)
+				throw new ArgumentException($"a push payload holds {MaxPayload} bytes at most", nameof(plaintext));
+			var serverPublic = PublicPoint(server);
+			var shared = SharedSecret(server, clientPublicKey);
+			// RFC 8291 3.3 and 3.4: PRK_key = HMAC-SHA-256(auth, ecdh); IKM = HKDF-Expand(PRK_key, "WebPush: info" 0x00
+			// ua_public as_public, 32)
+			var keyInfo = Concat(Encoding.ASCII.GetBytes("WebPush: info\0"), clientPublicKey, serverPublic);
+			var ikm = HKDF.Expand(HashAlgorithmName.SHA256, HKDF.Extract(HashAlgorithmName.SHA256, shared, authSecret), 32, keyInfo);
+			// RFC 8188 2.2 and 2.3: the content encryption key and the nonce, from the salt
+			var prk = HKDF.Extract(HashAlgorithmName.SHA256, ikm, salt);
+			var cek = HKDF.Expand(HashAlgorithmName.SHA256, prk, 16, Encoding.ASCII.GetBytes("Content-Encoding: aes128gcm\0"));
+			var nonce = HKDF.Expand(HashAlgorithmName.SHA256, prk, 12, Encoding.ASCII.GetBytes("Content-Encoding: nonce\0"));
+			// one record, the last: the payload, its delimiter 0x02, no padding
+			var record = new byte[plaintext.Length + 1];
+			plaintext.CopyTo(record);
+			record[^1] = 0x02;
+			var encrypted = Seal(cek, nonce, record);
+			// RFC 8188 2.1's header: the salt, the record size, the key id's length and the key id (RFC 8291: our public key)
+			var body = new byte[SaltLength + 4 + 1 + serverPublic.Length + encrypted.Length];
+			salt.CopyTo(body, 0);
+			BinaryPrimitives.WriteUInt32BigEndian(body.AsSpan(SaltLength), RecordSize);
+			body[SaltLength + 4] = (byte)serverPublic.Length;
+			serverPublic.CopyTo(body, SaltLength + 5);
+			encrypted.CopyTo(body, SaltLength + 5 + serverPublic.Length);
+			return new Message(body, "aes128gcm", salt, serverPublic);
+		}
+
+		public static Message AesGcm(ReadOnlySpan<byte> plaintext, byte[] clientPublicKey, byte[] authSecret)
+		{
+			using var server = ECDiffieHellman.Create(ECCurve.NamedCurves.nistP256);
+			return AesGcm(plaintext, clientPublicKey, authSecret, server, RandomNumberGenerator.GetBytes(SaltLength));
+		}
+
+		public static Message AesGcm(ReadOnlySpan<byte> plaintext, byte[] clientPublicKey, byte[] authSecret, ECDiffieHellman server, byte[] salt)
+		{
+			if (plaintext.Length > MaxPayload)
+				throw new ArgumentException($"a push payload holds {MaxPayload} bytes at most", nameof(plaintext));
+			var serverPublic = PublicPoint(server);
+			var shared = SharedSecret(server, clientPublicKey);
+			// the draft's: IKM = HKDF(salt: auth, ecdh, "Content-Encoding: auth" 0x00, 32), then the key and nonce from the salt
+			// over a context of both public keys, each after its length
+			var ikm = HKDF.Expand(HashAlgorithmName.SHA256, HKDF.Extract(HashAlgorithmName.SHA256, shared, authSecret), 32,
+				Encoding.ASCII.GetBytes("Content-Encoding: auth\0"));
+			var context = Concat(Encoding.ASCII.GetBytes("P-256\0"), Length16(clientPublicKey), clientPublicKey, Length16(serverPublic), serverPublic);
+			var prk = HKDF.Extract(HashAlgorithmName.SHA256, ikm, salt);
+			var cek = HKDF.Expand(HashAlgorithmName.SHA256, prk, 16, Concat(Encoding.ASCII.GetBytes("Content-Encoding: aesgcm\0"), context));
+			var nonce = HKDF.Expand(HashAlgorithmName.SHA256, prk, 12, Concat(Encoding.ASCII.GetBytes("Content-Encoding: nonce\0"), context));
+			// two bytes saying how much padding follows (none), then the payload
+			var padded = new byte[2 + plaintext.Length];
+			plaintext.CopyTo(padded.AsSpan(2));
+			return new Message(Seal(cek, nonce, padded), "aesgcm", salt, serverPublic);
+		}
+
+		/// <summary>A client's public key: an uncompressed point on P-256, or a CryptographicException.</summary>
+		public static ECDiffieHellman ImportPublic(byte[] point)
+		{
+			if (point is not { Length: 65 } || point[0] != 0x04)
+				throw new CryptographicException("not an uncompressed P-256 point");
+			var key = ECDiffieHellman.Create(new ECParameters
+			{
+				Curve = ECCurve.NamedCurves.nistP256,
+				Q = new ECPoint { X = point[1..33], Y = point[33..] }
+			});
+			return key;
+		}
+
+		/// <summary>Whether a subscription's keys can be encrypted to: a point on P-256 and a 16-byte secret.</summary>
+		public static bool AreUsable(byte[] p256dh, byte[] auth)
+		{
+			if (auth is not { Length: 16 })
+				return false;
+			try
+			{
+				using var key = ImportPublic(p256dh);
+				using var probe = ECDiffieHellman.Create(ECCurve.NamedCurves.nistP256);
+				probe.DeriveRawSecretAgreement(key.PublicKey);
+				return true;
+			}
+			catch (CryptographicException)
+			{
+				return false;
+			}
+		}
+
+		public static byte[] PublicPoint(ECAlgorithm key)
+		{
+			var parameters = key.ExportParameters(false);
+			return [0x04, .. parameters.Q.X, .. parameters.Q.Y];
+		}
+
+		public static string Base64Url(ReadOnlySpan<byte> bytes) =>
+			Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+
+		/// <summary>base64url or base64, padded or not, as clients send keys; null when it is neither.</summary>
+		public static byte[] FromBase64Url(string text)
+		{
+			if (string.IsNullOrWhiteSpace(text))
+				return default;
+			var normal = text.Trim().TrimEnd('=').Replace('-', '+').Replace('_', '/');
+			normal = normal.PadRight(normal.Length + (4 - normal.Length % 4) % 4, '=');
+			var bytes = new byte[normal.Length * 3 / 4];
+			return Convert.TryFromBase64String(normal, bytes, out var written) ? bytes[..written] : default;
+		}
+
+		static byte[] SharedSecret(ECDiffieHellman server, byte[] clientPublicKey)
+		{
+			using var client = ImportPublic(clientPublicKey);
+			return server.DeriveRawSecretAgreement(client.PublicKey);
+		}
+
+		static byte[] Seal(byte[] key, byte[] nonce, byte[] plaintext)
+		{
+			var output = new byte[plaintext.Length + TagLength];
+			using var aes = new AesGcm(key, TagLength);
+			aes.Encrypt(nonce, plaintext, output.AsSpan(0, plaintext.Length), output.AsSpan(plaintext.Length));
+			return output;
+		}
+
+		static byte[] Length16(byte[] value)
+		{
+			var length = new byte[2];
+			BinaryPrimitives.WriteUInt16BigEndian(length, (ushort)value.Length);
+			return length;
+		}
+
+		static byte[] Concat(params byte[][] parts)
+		{
+			var all = new byte[parts.Sum(p => p.Length)];
+			var at = 0;
+			foreach (var part in parts)
+			{
+				part.CopyTo(all, at);
+				at += part.Length;
+			}
+			return all;
+		}
+	}
+}

PrivaPub/Infrastructure/Push/WebPushJob.cs

@@ -0,0 +1,264 @@
+using Microsoft.Extensions.Localization;
+using Microsoft.Extensions.Options;
+
+using MongoDB.Entities;
+
+using OpenIddict.Abstractions;
+
+using PrivaPub.Api.Mastodon.Controllers;
+using PrivaPub.Api.Mastodon.Mappers;
+using PrivaPub.Domain.Instance;
+using PrivaPub.Domain.Moderation;
+using PrivaPub.Domain.Social;
+using PrivaPub.Federation.Actors;
+using PrivaPub.Infrastructure.Http;
+using PrivaPub.Infrastructure.Jobs;
+using PrivaPub.Models.Jobs;
+using PrivaPub.Models.Social;
+using PrivaPub.Models.User;
+using PrivaPub.Resources;
+
+using System.Net;
+using System.Net.Http.Headers;
+using System.Net.Sockets;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+
+using static OpenIddict.Abstractions.OpenIddictConstants;
+
+namespace PrivaPub.Infrastructure.Push
+{
+	// Sends one Web Push notification to one subscription (JobKind.SendPush, queued by WebPushDispatcher; completion
+	// program R9), as Mastodon's Web::PushNotificationWorker does:
+	// - the payload is Mastodon's (access_token, preferred_locale, notification_id, notification_type, icon, title, body), built
+	//   when it is sent, as the persona sees the notification then (one it can no longer see, or dismissed meanwhile, is not
+	//   sent), its access_token the subscription's own: the token is checked to be valid and the persona's first;
+	// - encrypted for the client alone (WebPushCrypto): RFC 8291 aes128gcm with RFC 8292's `vapid t=, k=` for a standard
+	//   subscription, otherwise the aesgcm draft with Encryption and Crypto-Key and `WebPush <jwt>`; the JWT (Vapid) names the
+	//   push service's origin (aud), lasts twelve hours (exp) and the server's contact (sub: mailto: the contact email, or
+	//   the server's address; never a persona);
+	// - TTL two days and Urgency normal, as Mastodon's;
+	// - through the `push` client: public addresses only, https only, no redirects, small timeouts (the federation client's
+	//   safe handler, with the pasture's exceptions where Federation says so).
+	// A 404 or 410 means the subscription is gone: it is deleted. 408, 429, a 5xx, a timeout or a broken connection retry on
+	// the jobs' backoff; any other answer drops the push (logged by the push service's host alone).
+	public class WebPushJob : IJobHandler
+	{
+		public const string ClientName = "push";
+		public static readonly TimeSpan RequestTimeout = TimeSpan.FromSeconds(15);
+		public static readonly TimeSpan ConnectTimeout = TimeSpan.FromSeconds(5);
+		// Mastodon's Web::PushNotificationWorker::TTL and URGENCY
+		const int TimeToLive = 48 * 3600;
+		const string Urgency = "normal";
+		const int BodyLength = 140;
+
+		readonly IHttpClientFactory _http;
+		readonly IVapid _vapid;
+		readonly IServiceScopeFactory _scopes;
+		readonly IInstanceSettings _settings;
+		readonly ILocalActorService _localActors;
+		readonly IOptionsMonitor<FederationOptions> _federation;
+		readonly IStringLocalizer<GenericRes> _localizer;
+		readonly ILogger<WebPushJob> _logger;
+
+		public WebPushJob(IHttpClientFactory http, IVapid vapid, IServiceScopeFactory scopes, IInstanceSettings settings, ILocalActorService localActors,
+			IOptionsMonitor<FederationOptions> federation, IStringLocalizer<GenericRes> localizer, ILogger<WebPushJob> logger)
+		{
+			_http = http;
+			_vapid = vapid;
+			_scopes = scopes;
+			_settings = settings;
+			_localActors = localActors;
+			_federation = federation;
+			_localizer = localizer;
+			_logger = logger;
+		}
+
+		public JobKind Kind => JobKind.SendPush;
+		public int Concurrency => 4;
+		public int MaxAttempts => 6;
+		public int PerHostLimit => 4;
+
+		public async Task<JobOutcome> Handle(Job job, CancellationToken token)
+		{
+			var payload = JsonSerializer.Deserialize<PushPayload>(job.Payload ?? "null");
+			if (string.IsNullOrEmpty(payload?.SubscriptionId) || string.IsNullOrEmpty(payload.NotificationId))
+				return JobOutcome.Done;
+			var subscriptionId = payload.SubscriptionId;
+			var subscription = await DB.Default.Find<PushSubscription>().Match(s => s.ID == subscriptionId).ExecuteFirstAsync(token);
+			if (subscription == default)
+				return JobOutcome.Done;
+			// a persona held back (suspended, its login banned) gets no push
+			if (Restrictions.IsSuspended(subscription.AvatarId))
+				return JobOutcome.Done;
+			var notificationId = payload.NotificationId;
+			var avatarId = subscription.AvatarId;
+			var notification = await DB.Default.Find<Notification>().Match(n => n.ID == notificationId && n.AvatarId == avatarId).ExecuteFirstAsync(token);
+			if (notification == default || !await WebPush.Pushable(subscription, notification, token))
+				return JobOutcome.Done;
+			if (!Uri.TryCreate(subscription.Endpoint, UriKind.Absolute, out var endpoint) || !IsAllowed(endpoint, _federation.CurrentValue))
+				return JobOutcome.Dead("endpoint");
+
+			byte[] json;
+			using (var scope = _scopes.CreateScope())
+			{
+				// the token the subscription was made with must still be valid, and the persona's: it goes into the payload
+				if (!await TokenHolds(scope.ServiceProvider.GetRequiredService<IOpenIddictTokenManager>(), subscription, token))
+				{
+					await WebPush.ForgetToken(subscription.TokenId);
+					return JobOutcome.Done;
+				}
+				var avatar = await DB.Default.Find<Avatar>().Match(a => a.ID == avatarId && a.DeletionAt == null).ExecuteFirstAsync(token);
+				if (avatar == default)
+				{
+					await WebPush.Forget(new[] { avatarId });
+					return JobOutcome.Done;
+				}
+				var mapped = (await scope.ServiceProvider.GetRequiredService<MastodonMapper>().Notifications(new List<Notification> { notification }, avatarId, token))
+					.FirstOrDefault();
+				if (mapped == default)
+					return JobOutcome.Done;
+				json = JsonSerializer.SerializeToUtf8Bytes(new Dictionary<string, object>
+				{
+					["access_token"] = subscription.AccessToken,
+					["preferred_locale"] = Locale(avatar, scope.ServiceProvider),
+					["notification_id"] = notification.ID,
+					["notification_type"] = WebPush.AlertOf(notification.Type),
+					["icon"] = mapped.Account?.AvatarStatic ?? mapped.Account?.Avatar,
+					["title"] = Title(notification, mapped),
+					["body"] = Body(mapped)
+				});
+			}
+
+			var key = await _vapid.Key(token);
+			var p256dh = WebPushCrypto.FromBase64Url(subscription.P256dh);
+			var auth = WebPushCrypto.FromBase64Url(subscription.Auth);
+			if (!WebPushCrypto.AreUsable(p256dh, auth))
+				return JobOutcome.Dead("keys");
+			var message = subscription.Standard ? WebPushCrypto.Aes128Gcm(json, p256dh, auth) : WebPushCrypto.AesGcm(json, p256dh, auth);
+			var jwt = key.Token(VapidKey.Audience(endpoint), Subject(), DateTime.UtcNow);
+
+			using var request = new HttpRequestMessage(HttpMethod.Post, endpoint) { Content = new ByteArrayContent(message.Body) };
+			request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
+			request.Content.Headers.ContentEncoding.Add(message.ContentEncoding);
+			request.Headers.TryAddWithoutValidation("TTL", TimeToLive.ToString(System.Globalization.CultureInfo.InvariantCulture));
+			request.Headers.TryAddWithoutValidation("Urgency", Urgency);
+			if (subscription.Standard)
+				request.Headers.TryAddWithoutValidation("Authorization", $"vapid t={jwt}, k={key.ForHeader}");
+			else
+			{
+				request.Headers.TryAddWithoutValidation("Authorization", $"WebPush {jwt}");
+				request.Headers.TryAddWithoutValidation("Encryption", $"salt={WebPushCrypto.Base64Url(message.Salt)}");
+				request.Headers.TryAddWithoutValidation("Crypto-Key", $"dh={WebPushCrypto.Base64Url(message.ServerPublicKey)};p256ecdsa={key.ForHeader}");
+			}
+
+			try
+			{
+				using var response = await _http.CreateClient(ClientName).SendAsync(request, HttpCompletionOption.ResponseHeadersRead, token);
+				var status = (int)response.StatusCode;
+				if (status is >= 200 and < 300)
+					return JobOutcome.Done;
+				if (response.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.Gone)
+				{
+					await DB.Default.DeleteAsync<PushSubscription>(subscription.ID);
+					_logger.LogInformation("{Kind}: {Host} answered {Status}, the subscription is gone", Kind, endpoint.Host, status);
+					return JobOutcome.Done;
+				}
+				if (response.StatusCode is HttpStatusCode.RequestTimeout or HttpStatusCode.TooManyRequests || status >= 500)
+					return JobOutcome.Retry($"status {status}");
+				_logger.LogWarning("{Kind}: {Host} refused a push with {Status}; it is dropped", Kind, endpoint.Host, status);
+				return JobOutcome.Dead($"status {status}");
+			}
+			catch (BlockedDestinationException)
+			{
+				_logger.LogWarning("{Kind}: {Host} does not resolve to a public address; the push is dropped", Kind, endpoint.Host);
+				return JobOutcome.Dead("blocked destination");
+			}
+			catch (TaskCanceledException) when (!token.IsCancellationRequested)
+			{
+				return JobOutcome.Retry("timeout");
+			}
+			catch (HttpRequestException ex) when (ex.InnerException is BlockedDestinationException)
+			{
+				_logger.LogWarning("{Kind}: {Host} does not resolve to a public address; the push is dropped", Kind, endpoint.Host);
+				return JobOutcome.Dead("blocked destination");
+			}
+			catch (Exception ex) when (ex is HttpRequestException or IOException or SocketException)
+			{
+				return JobOutcome.Retry(ex.GetType().Name);
+			}
+		}
+
+		/// <summary>https, a host, no user information; plain http only on a test network (Federation:AllowPlainHttp, which
+		/// production refuses at start).</summary>
+		public static bool IsAllowed(Uri endpoint, FederationOptions options) =>
+			endpoint != default && endpoint.IsAbsoluteUri && !string.IsNullOrEmpty(endpoint.Host) && string.IsNullOrEmpty(endpoint.UserInfo)
+			&& (endpoint.Scheme == Uri.UriSchemeHttps || options?.AllowPlainHttp == true && endpoint.Scheme == Uri.UriSchemeHttp);
+
+		static async Task<bool> TokenHolds(IOpenIddictTokenManager tokens, PushSubscription subscription, CancellationToken token)
+		{
+			if (string.IsNullOrEmpty(subscription.TokenId) || string.IsNullOrEmpty(subscription.AccessToken))
+				return false;
+			var stored = await tokens.FindByIdAsync(subscription.TokenId, token);
+			if (stored == default || !await tokens.HasStatusAsync(stored, Statuses.Valid, token))
+				return false;
+			if (await tokens.GetExpirationDateAsync(stored, token) is { } expires && expires < DateTimeOffset.UtcNow)
+				return false;
+			return await tokens.GetSubjectAsync(stored, token) == subscription.AvatarId;
+		}
+
+		// RFC 8292's sub: how the push service reaches the server's operator. The contact email the administrator gave, or
+		// the server's own address; never a persona. (A server on plain http, a test network, has no https: address to give,
+		// so it names a mailbox at its host: RFC 8292 takes only mailto: and https:.)
+		string Subject()
+		{
+			var email = _settings.Current.ContactEmail?.Trim();
+			if (!string.IsNullOrEmpty(email) && !email.Any(char.IsWhiteSpace) && email.Contains('@'))
+				return "mailto:" + email;
+			var address = _localActors.BaseAddress;
+			return Uri.TryCreate(address, UriKind.Absolute, out var base_) && base_.Scheme != Uri.UriSchemeHttps
+				? "mailto:privapub@" + base_.Host
+				: address;
+		}
+
+		// the persona's language (its default for posts), else the server's first
+		static string Locale(Avatar avatar, IServiceProvider services)
+		{
+			var language = avatar.Settings?.DefaultLanguage;
+			return string.IsNullOrWhiteSpace(language) ? InstanceController.LanguageCodes(services)[0] : language.Trim();
+		}
+
+		// Mastodon's notification_mailer subjects
+		string Title(Notification notification, Api.Mastodon.Entities.Notification mapped)
+		{
+			var name = string.IsNullOrWhiteSpace(mapped.Account?.DisplayName) ? mapped.Account?.Username ?? string.Empty : mapped.Account.DisplayName;
+			return notification.Type switch
+			{
+				NotificationType.Mention => string.Format(_localizer["You were mentioned by {0}"], name),
+				NotificationType.Status => string.Format(_localizer["{0} just posted"], name),
+				NotificationType.Reblog => string.Format(_localizer["{0} boosted your post"], name),
+				NotificationType.Follow => string.Format(_localizer["{0} is now following you"], name),
+				NotificationType.FollowRequest => string.Format(_localizer["Pending follower: {0}"], name),
+				NotificationType.Favourite => string.Format(_localizer["{0} favorited your post"], name),
+				NotificationType.Poll => string.Format(_localizer["A poll by {0} has ended"], name),
+				NotificationType.Update => string.Format(_localizer["{0} edited a post"], name),
+				NotificationType.Quote => string.Format(_localizer["{0} quoted your post"], name),
+				NotificationType.Reaction => string.Format(_localizer["{0} reacted to your post with {1}"], name, notification.Emoji),
+				NotificationType.ModerationWarning => _localizer["You have received a moderation warning"],
+				_ => name
+			};
+		}
+
+		// Mastodon's: the post's warning, else its words, else the account's bio, without tags, 140 characters at most
+		static string Body(Api.Mastodon.Entities.Notification mapped)
+		{
+			var source = !string.IsNullOrWhiteSpace(mapped.Status?.SpoilerText) ? mapped.Status.SpoilerText
+				: mapped.Status?.Content ?? mapped.ModerationWarning?.Text ?? mapped.Account?.Note ?? string.Empty;
+			var text = WebUtility.HtmlDecode(Tags.Replace(Breaks.Replace(source, "\n"), string.Empty)).Trim();
+			return text.Length <= BodyLength ? text : text[..(BodyLength - 3)] + "...";
+		}
+
+		static readonly Regex Breaks = new(@"<br\s*/?>|</p>\s*<p[^>]*>", RegexOptions.IgnoreCase | RegexOptions.Compiled);
+		static readonly Regex Tags = new("<[^>]*>", RegexOptions.Compiled);
+	}
+}