@sdxc/activitypub 0.0.0-pre.1

package/dist/keys.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The signing keys of a local actor: generating the RSA pair once, importing the stored
+ * private key with its public half derived from it, and the `publicKey` member an actor
+ * document publishes, plus importing a remote actor's published key for verification.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { CryptoError } from "@sdxc/crypto";
+import type { ActivityPub } from "./lib/types.js";
+/**
+ * The keys a local actor signs with: the RSA pair every HTTP signature from the actor uses,
+ * and the `publicKey` member its actor document publishes so remote servers can verify them.
+ */
+export declare class ActorKeys {
+    /** The actor's id. */
+    readonly actor: string;
+    /** `id` is `<actor>#main-key`, the `keyId` every HTTP signature from the actor names. */
+    readonly rsa: ActorKeys.Rsa;
+    /** Present once FEP-8b32 proofs are enabled. */
+    readonly ed25519: ActorKeys.Ed25519 | null;
+    /**
+     * @param init - The actor and keys already imported; `ActorKeys.import` builds them from
+     *   a stored PEM.
+     */
+    constructor(init: ActorKeys.Init);
+    /**
+     * Generates an RSA 2048 key pair for an actor. Run it once and store `privateKeyPem` as
+     * a secret: every follower verifies against the published half, so a new pair means an
+     * actor `Update` delivered to all of them.
+     *
+     * @returns Both halves as PEM, or a `CryptoError` when Web Crypto refuses.
+     * @example let generated = await ActorKeys.generate();
+     */
+    static generate(): Promise<Result<ActorKeys.Generated, CryptoError>>;
+    /**
+     * Imports an actor's stored private key. The public half is derived from the private
+     * key's JWK, so only one secret is stored and the published key always matches the
+     * signing one. The imported private key stays inside Web Crypto, unextractable.
+     *
+     * @param options - The actor's id and its PKCS#8 PEM.
+     * @returns The keys, or an `InvalidKeyError` for a PEM that is not a PKCS#8 RSA key.
+     * @example let keys = await ActorKeys.import({ actor: ACTOR_ID, privateKeyPem: env.ACTIVITYPUB_PRIVATE_KEY });
+     */
+    static import(options: ActorKeys.ImportOptions): Promise<Result<ActorKeys, CryptoError>>;
+    /** The `keyId` signatures name, `<actor>#main-key`, which is where Mastodon looks. */
+    get id(): string;
+    /**
+     * The `publicKey` member of the actor document, under `<actor>#main-key` with `owner`
+     * naming the actor, which is where Mastodon looks for the key a signature names.
+     *
+     * @example let actor = { ...ACTOR, publicKey: keys.publicKey };
+     */
+    get publicKey(): ActivityPub.PublicKey;
+}
+export declare namespace ActorKeys {
+    /** A freshly generated pair, armored for storage as secrets. */
+    interface Generated {
+        /** PKCS#8; the only value that must stay secret, and what `ActorKeys.import` reads. */
+        privateKeyPem: string;
+        /** SPKI, as an actor's `publicKey.publicKeyPem` publishes it. */
+        publicKeyPem: string;
+    }
+    /** What `ActorKeys.import` reads. */
+    interface ImportOptions {
+        /** The actor's id, which names the key `<actor>#main-key`. */
+        actor: string;
+        /** PKCS#8 PEM, as `ActorKeys.generate` produced it. */
+        privateKeyPem: string;
+    }
+    /** The RSA half every HTTP signature uses. */
+    interface Rsa {
+        id: string;
+        privateKey: CryptoKey;
+        publicKeyPem: string;
+    }
+    /** The Ed25519 key FEP-8b32 proofs are signed with. */
+    interface Ed25519 {
+        id: string;
+        privateKey: CryptoKey;
+        publicKeyMultibase: string;
+    }
+    /** Keys already imported into Web Crypto. */
+    interface Init {
+        actor: string;
+        rsa: Rsa;
+        /** @default null */
+        ed25519?: Ed25519 | null;
+    }
+}
+/**
+ * Imports a remote actor's `publicKeyPem` for verifying its signatures. SPKI RSA keys
+ * import as RSASSA-PKCS1-v1_5 SHA-256 and SPKI Ed25519 keys as Ed25519, the two kinds
+ * servers publish there.
+ *
+ * @param pem - The SPKI PEM a remote actor published.
+ * @returns A verify-only key, or an `InvalidKeyError` for anything else.
+ */
+export declare function importPublicKey(pem: string): Promise<Result<CryptoKey, CryptoError>>;

package/dist/keys.js

@@ -0,0 +1,147 @@
+import { CryptoError, InvalidKeyError, Pem } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+/** RSASSA-PKCS1-v1_5 over SHA-256, the only algorithm every Mastodon version verifies. */
+const RSA_ALGORITHM = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+/** Ed25519, which some servers publish under `publicKeyPem` instead of an RSA key. */
+const ED25519_ALGORITHM = { name: "Ed25519" };
+/** The modulus length Mastodon generates, so a key this package makes looks like theirs. */
+const RSA_MODULUS_LENGTH = 2048;
+/** The PEM label of a PKCS#8 private key. */
+const PRIVATE_KEY_LABEL = "PRIVATE KEY";
+/** The PEM label of an SPKI public key, which is what `publicKeyPem` carries. */
+const PUBLIC_KEY_LABEL = "PUBLIC KEY";
+/** The fragment Mastodon puts its key under, and where it looks for one on an actor. */
+const MAIN_KEY_FRAGMENT = "#main-key";
+/**
+ * The keys a local actor signs with: the RSA pair every HTTP signature from the actor uses,
+ * and the `publicKey` member its actor document publishes so remote servers can verify them.
+ */
+export class ActorKeys {
+    /** The actor's id. */
+    actor;
+    /** `id` is `<actor>#main-key`, the `keyId` every HTTP signature from the actor names. */
+    rsa;
+    /** Present once FEP-8b32 proofs are enabled. */
+    ed25519;
+    /**
+     * @param init - The actor and keys already imported; `ActorKeys.import` builds them from
+     *   a stored PEM.
+     */
+    constructor(init) {
+        this.actor = init.actor;
+        this.rsa = init.rsa;
+        this.ed25519 = init.ed25519 ?? null;
+    }
+    /**
+     * Generates an RSA 2048 key pair for an actor. Run it once and store `privateKeyPem` as
+     * a secret: every follower verifies against the published half, so a new pair means an
+     * actor `Update` delivered to all of them.
+     *
+     * @returns Both halves as PEM, or a `CryptoError` when Web Crypto refuses.
+     * @example let generated = await ActorKeys.generate();
+     */
+    static async generate() {
+        let pair;
+        let pkcs8;
+        let spki;
+        try {
+            pair = await crypto.subtle.generateKey({
+                ...RSA_ALGORITHM,
+                modulusLength: RSA_MODULUS_LENGTH,
+                publicExponent: new Uint8Array([1, 0, 1]),
+            }, true, ["sign", "verify"]);
+            pkcs8 = await crypto.subtle.exportKey("pkcs8", pair.privateKey);
+            spki = await crypto.subtle.exportKey("spki", pair.publicKey);
+        }
+        catch (cause) {
+            return failure(new CryptoError(`Could not generate an RSA key pair: ${reasonOf(cause)}`));
+        }
+        let privateKeyPem = Pem.encode(pkcs8, PRIVATE_KEY_LABEL);
+        if (isFailure(privateKeyPem))
+            return privateKeyPem;
+        let publicKeyPem = Pem.encode(spki, PUBLIC_KEY_LABEL);
+        if (isFailure(publicKeyPem))
+            return publicKeyPem;
+        return success({ privateKeyPem: privateKeyPem.data, publicKeyPem: publicKeyPem.data });
+    }
+    /**
+     * Imports an actor's stored private key. The public half is derived from the private
+     * key's JWK, so only one secret is stored and the published key always matches the
+     * signing one. The imported private key stays inside Web Crypto, unextractable.
+     *
+     * @param options - The actor's id and its PKCS#8 PEM.
+     * @returns The keys, or an `InvalidKeyError` for a PEM that is not a PKCS#8 RSA key.
+     * @example let keys = await ActorKeys.import({ actor: ACTOR_ID, privateKeyPem: env.ACTIVITYPUB_PRIVATE_KEY });
+     */
+    static async import(options) {
+        let der = Pem.decode(options.privateKeyPem, PRIVATE_KEY_LABEL);
+        if (isFailure(der)) {
+            return failure(new InvalidKeyError("the private key must be PKCS#8 PEM (BEGIN PRIVATE KEY)"));
+        }
+        let privateKey;
+        let spki;
+        try {
+            let extractable = await crypto.subtle.importKey("pkcs8", der.data, RSA_ALGORITHM, true, [
+                "sign",
+            ]);
+            let jwk = await crypto.subtle.exportKey("jwk", extractable);
+            let publicKey = await crypto.subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, RSA_ALGORITHM, true, ["verify"]);
+            spki = await crypto.subtle.exportKey("spki", publicKey);
+            privateKey = await crypto.subtle.importKey("pkcs8", der.data, RSA_ALGORITHM, false, ["sign"]);
+        }
+        catch (cause) {
+            return failure(new InvalidKeyError(`not an RSA private key: ${reasonOf(cause)}`));
+        }
+        let publicKeyPem = Pem.encode(spki, PUBLIC_KEY_LABEL);
+        if (isFailure(publicKeyPem))
+            return publicKeyPem;
+        return success(new ActorKeys({
+            actor: options.actor,
+            rsa: {
+                id: `${options.actor}${MAIN_KEY_FRAGMENT}`,
+                privateKey,
+                publicKeyPem: publicKeyPem.data,
+            },
+        }));
+    }
+    /** The `keyId` signatures name, `<actor>#main-key`, which is where Mastodon looks. */
+    get id() {
+        return this.rsa.id;
+    }
+    /**
+     * The `publicKey` member of the actor document, under `<actor>#main-key` with `owner`
+     * naming the actor, which is where Mastodon looks for the key a signature names.
+     *
+     * @example let actor = { ...ACTOR, publicKey: keys.publicKey };
+     */
+    get publicKey() {
+        return { id: this.rsa.id, owner: this.actor, publicKeyPem: this.rsa.publicKeyPem };
+    }
+}
+/**
+ * Imports a remote actor's `publicKeyPem` for verifying its signatures. SPKI RSA keys
+ * import as RSASSA-PKCS1-v1_5 SHA-256 and SPKI Ed25519 keys as Ed25519, the two kinds
+ * servers publish there.
+ *
+ * @param pem - The SPKI PEM a remote actor published.
+ * @returns A verify-only key, or an `InvalidKeyError` for anything else.
+ */
+export async function importPublicKey(pem) {
+    let der = Pem.decode(pem, PUBLIC_KEY_LABEL);
+    if (isFailure(der)) {
+        return failure(new InvalidKeyError("the public key must be SPKI PEM (BEGIN PUBLIC KEY)"));
+    }
+    for (let algorithm of [RSA_ALGORITHM, ED25519_ALGORITHM]) {
+        try {
+            return success(await crypto.subtle.importKey("spki", der.data, algorithm, false, ["verify"]));
+        }
+        catch {
+            continue;
+        }
+    }
+    return failure(new InvalidKeyError("the public key is neither RSA nor Ed25519"));
+}
+/** The message of a thrown value, for an error that wraps it. */
+function reasonOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/lib/availability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which remote origins have been failing deliveries, kept in the app's cache so fan-out
+ * stops queueing work for a server that has been down for days, and so one inbound
+ * activity that verifies from that server makes it reachable again.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Cache } from "@sdxc/cache";
+/** Failures lasting longer than this make an origin unavailable, the window Mastodon uses. */
+export declare const UNAVAILABLE_AFTER: number;
+/**
+ * Records a failed delivery to `origin`. The first failure starts the window and later
+ * ones keep it, so the window measures how long the origin has been failing.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin of the inbox that failed.
+ * @param now - The current time in milliseconds.
+ */
+export declare function recordFailure(cache: Cache, origin: string, now?: number): Promise<void>;
+/**
+ * Clears the failure window of `origin`, after a delivery succeeded or an activity from it
+ * verified. A cache failure leaves the record, which costs at most a skipped delivery.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin that answered.
+ */
+export declare function recordSuccess(cache: Cache, origin: string): Promise<void>;
+/**
+ * Whether `origin` has been failing for longer than {@link UNAVAILABLE_AFTER}. A cache
+ * failure reads as available, so a broken cache never stops delivery.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin about to receive a delivery.
+ * @param now - The current time in milliseconds.
+ */
+export declare function isUnavailable(cache: Cache, origin: string, now?: number): Promise<boolean>;

package/dist/lib/availability.js

@@ -0,0 +1,52 @@
+import { toMs } from "@sdxc/duration";
+import { isFailure } from "@sdxc/result";
+/** Failures lasting longer than this make an origin unavailable, the window Mastodon uses. */
+export const UNAVAILABLE_AFTER = toMs("7 days");
+/** Outlives the window, so a failing origin is still remembered when it crosses it. */
+const RECORD_TTL = "30 days";
+/** One entry per origin, so every inbox on a server shares its standing. */
+function keyOf(origin) {
+    return `activitypub:unavailable:${origin}`;
+}
+/**
+ * Records a failed delivery to `origin`. The first failure starts the window and later
+ * ones keep it, so the window measures how long the origin has been failing.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin of the inbox that failed.
+ * @param now - The current time in milliseconds.
+ */
+export async function recordFailure(cache, origin, now = Date.now()) {
+    let current = await cache.read(keyOf(origin));
+    if (isFailure(current))
+        return;
+    if (current.data !== null && typeof current.data.since === "number")
+        return;
+    await cache.write(keyOf(origin), { since: now }, { ttl: RECORD_TTL });
+}
+/**
+ * Clears the failure window of `origin`, after a delivery succeeded or an activity from it
+ * verified. A cache failure leaves the record, which costs at most a skipped delivery.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin that answered.
+ */
+export async function recordSuccess(cache, origin) {
+    await cache.delete(keyOf(origin));
+}
+/**
+ * Whether `origin` has been failing for longer than {@link UNAVAILABLE_AFTER}. A cache
+ * failure reads as available, so a broken cache never stops delivery.
+ *
+ * @param cache - The app's cache.
+ * @param origin - The origin about to receive a delivery.
+ * @param now - The current time in milliseconds.
+ */
+export async function isUnavailable(cache, origin, now = Date.now()) {
+    let current = await cache.read(keyOf(origin));
+    if (isFailure(current) || current.data === null)
+        return false;
+    if (typeof current.data.since !== "number")
+        return false;
+    return now - current.data.since > UNAVAILABLE_AFTER;
+}

package/dist/lib/compact.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The wire variations of compacted ActivityStreams, each read into one shape: single
+ * values or arrays, IRIs or embedded objects, plain or language-mapped text, and every
+ * spelling of the public collection. JSON-LD is never expanded, so no context is fetched.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Issue, Schema } from "remix/data-schema";
+import { createSchema } from "remix/data-schema";
+import type { ActivityPub } from "./types.js";
+/** The path and options data-schema hands a validator, read to place nested issues. */
+export type Context = Parameters<Parameters<typeof createSchema>[0]>[1];
+/** A decoded JSON object, read member by member. */
+export type JsonObject = Record<string, unknown>;
+/**
+ * Whether a decoded value is a plain JSON object.
+ *
+ * @param value - Any decoded JSON value.
+ */
+export declare function isObject(value: unknown): value is JsonObject;
+/**
+ * Runs a schema on a member, so its issues point at that member.
+ *
+ * @param schema - The member's schema.
+ * @param value - The member's value.
+ * @param context - The enclosing value's context.
+ * @param key - The member name or array index.
+ * @template Output - What the schema produces.
+ */
+export declare function runAt<Output>(schema: Schema<unknown, Output>, value: unknown, context: Context, key: string | number): {
+    value: Output;
+    issues?: undefined;
+} | {
+    issues: readonly Issue[];
+};
+/**
+ * The public collection's IRI for any spelling of it; every other IRI unchanged.
+ *
+ * @param iri - An addressing entry.
+ */
+export declare function normalizePublic(iri: string): string;
+/**
+ * An absolute IRI, which a document's `id` must be: every ownership check compares its
+ * origin, and a relative one has none.
+ *
+ * @param label - The member, for the message.
+ */
+export declare function absoluteIri(label: string): Schema<unknown, string>;
+/**
+ * An absolute IRI that may be absent, `null` then.
+ *
+ * @param label - The member, for the message.
+ */
+export declare function optionalAbsoluteIri(label: string): Schema<unknown, string | null>;
+/**
+ * A `type` sent as a string or an array, read as one name: the first a caller knows,
+ * else the first listed. An `as:` prefix is dropped, since it names the same term.
+ *
+ * @param known - Type names to prefer when several are listed.
+ */
+export declare function documentType(known: ReadonlySet<string>): Schema<unknown, string>;
+/**
+ * A list of IRIs sent as one entry or an array, each an IRI or an embedded object, read
+ * as the IRIs alone. With `addressing`, every spelling of the public collection reads
+ * as `PUBLIC`.
+ *
+ * @param options - Whether the list addresses an audience.
+ */
+export declare function iris(options?: {
+    addressing?: boolean;
+}): Schema<unknown, string[]>;
+/**
+ * One reference read as its IRI: a string, an embedded object's `id`, a Link's `href`, or
+ * the first of an array. Absent reads as `null`; with `required`, absent fails.
+ *
+ * @param options - Whether the member must be present, and its name for the message.
+ */
+export declare function iri(options: {
+    required: true;
+    label: string;
+}): Schema<unknown, string>;
+export declare function iri(options?: {
+    required?: false;
+    label?: string;
+}): Schema<unknown, string | null>;
+/** Text that may be absent: a string, or `null` when absent. */
+export declare function text(): Schema<unknown, string | null>;
+/** A language map (`contentMap`, `nameMap`, `summaryMap`), empty when absent. */
+export declare function languageMap(): Schema<unknown, Record<string, string>>;
+/**
+ * The plain value of a text member, falling back to the first entry of its language map
+ * when a sender sent only the map.
+ *
+ * @param plain - The plain value.
+ * @param map - The language map.
+ */
+export declare function withMapFallback(plain: string | null, map: Record<string, string>): string | null;
+/**
+ * A `url` sent as a string, a `Link` or an array of them, read as the page a person
+ * opens: the first `text/html` link, else the first link. A member that names no link
+ * at all reads as `null`.
+ */
+export declare function htmlUrl(): Schema<unknown, string | null>;
+/** An ISO 8601 date, `null` when absent. */
+export declare function date(): Schema<unknown, Date | null>;
+/** A boolean flag, `false` when absent. */
+export declare function flag(): Schema<unknown, boolean>;
+/** A count such as `totalItems`, `null` when absent. */
+export declare function count(): Schema<unknown, number | null>;
+/**
+ * An image sent as a string URL or an `Image` object (or an array of them), read as an
+ * `Image`. A value that names no URL reads as `null`.
+ *
+ * @param value - The member's value.
+ */
+export declare function readImage(value: unknown): ActivityPub.Image | null;
+/** An `icon` or `image`, `null` when absent or naming no URL. */
+export declare function image(): Schema<unknown, ActivityPub.Image | null>;
+/**
+ * `tag` entries this package models: hashtags, mentions and custom emoji. Entries of
+ * other types, and entries missing what their type requires, are dropped, since a tag
+ * decorates an object and never decides whether it can be read.
+ */
+export declare function tags(): Schema<unknown, ActivityPub.Tag[]>;
+/**
+ * `attachment` entries this package models: media files and profile fields. Other
+ * entries are dropped, for the same reason as tags.
+ */
+export declare function attachments(): Schema<unknown, ActivityPub.Attachment[]>;
+/**
+ * FEP-8b32 proofs, sent as one object or a set. An entry that is not a complete
+ * `DataIntegrityProof` is dropped, so verification treats the document as unproven.
+ */
+export declare function proofs(): Schema<unknown, ActivityPub.Proof[]>;
+/** FEP-521a `Multikey` entries of `assertionMethod`; other verification methods are dropped. */
+export declare function multikeys(): Schema<unknown, ActivityPub.Multikey[]>;
+/**
+ * An actor's `publicKey`, sent as one object or an array whose first complete entry is
+ * read. A key present but missing `id`, `owner` or `publicKeyPem` fails, since no
+ * signature from the actor could verify against it.
+ */
+export declare function publicKey(): Schema<unknown, ActivityPub.PublicKey | null>;
+/** An actor's `endpoints`, whose `sharedInbox` is `null` when absent. */
+export declare function endpoints(): Schema<unknown, ActivityPub.Endpoints>;