fix(api): enforce federation JSON-LD context (#295)

* fix(api): enforce federation jsonld context

* test(api): cover federation jsonld document routes

* docs(api): document federation jsonld helpers

* fix(docker): pin rtk installer version

* fix(docker): pin rtk installer script

Author: skulidropek

packages/api/src/api/contracts.ts

@@ -490,6 +490,26 @@ export type ContainerTaskSnapshot = {
   readonly agents: ReadonlyArray<AgentSession>
 }
 
+export const activityStreamsJsonLdContext = "https://www.w3.org/ns/activitystreams" as const
+export const forgeFedJsonLdContext = "https://forgefed.org/ns" as const
+export const securityJsonLdContext = "https://w3id.org/security/v1" as const
+export const activityForgeFedJsonLdContext = [
+  activityStreamsJsonLdContext,
+  forgeFedJsonLdContext
+] as const
+export const actorJsonLdContext = [
+  activityStreamsJsonLdContext,
+  securityJsonLdContext,
+  forgeFedJsonLdContext
+] as const
+export const federationJsonLdContentType =
+  `application/ld+json; profile="${activityStreamsJsonLdContext}"` as const
+export const federationJsonLdResponseContentType =
+  `${federationJsonLdContentType}; charset=utf-8` as const
+
+export type ActivityForgeFedJsonLdContext = typeof activityForgeFedJsonLdContext
+export type ActorJsonLdContext = typeof actorJsonLdContext
+
 export type ForgeFedTicket = {
   readonly id: string
   readonly attributedTo: string
@@ -550,7 +570,7 @@ export type CreateFollowRequest = {
 export type FollowStatus = "pending" | "accepted" | "rejected"
 
 export type ActivityPubFollowActivity = {
-  readonly "@context": string | ReadonlyArray<string>
+  readonly "@context": ActivityForgeFedJsonLdContext
   readonly id: string
   readonly type: "Follow"
   readonly actor: string
@@ -566,7 +586,7 @@ export type ActivityPubPublicKey = {
 }
 
 export type ActivityPubPerson = {
-  readonly "@context": "https://www.w3.org/ns/activitystreams"
+  readonly "@context": ActorJsonLdContext
   readonly type: "Person"
   readonly id: string
   readonly name: string
@@ -584,7 +604,7 @@ export type ActivityPubPerson = {
 }
 
 export type ActivityPubOrderedCollection = {
-  readonly "@context": "https://www.w3.org/ns/activitystreams" | ReadonlyArray<string>
+  readonly "@context": ActivityForgeFedJsonLdContext
   readonly type: "OrderedCollection"
   readonly id: string
   readonly totalItems: number

packages/api/src/http.ts

@@ -11,7 +11,7 @@ import * as Schema from "effect/Schema"
 import { renderError, type AppError } from "@effect-template/lib/usecases/errors"
 
 import { ApiAuthRequiredError, ApiBadRequestError, ApiConflictError, ApiInternalError, ApiNotFoundError, describeUnknown } from "./api/errors.js"
-import type { ApplyProjectRequest } from "./api/contracts.js"
+import { federationJsonLdResponseContentType, type ApplyProjectRequest } from "./api/contracts.js"
 import {
   AuthMenuRequestSchema,
   AuthTerminalSessionRequestSchema,
@@ -275,8 +275,23 @@ const binaryResponse = (data: Uint8Array, contentType: string, status = 200) =>
     )
   )
 
-const activityJsonResponse = (data: unknown, status: number) =>
-  textResponse(JSON.stringify(data), "application/activity+json; charset=utf-8", status)
+/**
+ * Serializes a federation JSON-LD document with the ForgeFed response content type.
+ *
+ * @param data - JSON-LD payload that satisfies the JSON.stringify serializability precondition.
+ * @param status - HTTP status code assigned to the response.
+ * @returns Effect that yields an HTTP text response containing the serialized JSON-LD document.
+ *
+ * @pure false
+ * @effect Delegates response allocation to textResponse and preserves no-store HTTP headers.
+ * @invariant successful responses always use federationJsonLdResponseContentType.
+ * @precondition data is JSON.stringify-serializable and status is a valid HTTP status code.
+ * @postcondition response body equals JSON.stringify(data) and response status equals status.
+ * @complexity O(n) time and O(n) space where n is the serialized JSON-LD payload size.
+ * @throws TypeError when data violates the JSON.stringify serializability precondition.
+ */
+const jsonLdResponse = (data: unknown, status: number) =>
+  textResponse(JSON.stringify(data), federationJsonLdResponseContentType, status)
 
 const parseQueryInt = (url: string, key: string, fallback: number): number => {
   const parsed = Number(new URL(url, "http://localhost").searchParams.get(key) ?? "")
@@ -595,6 +610,106 @@ export const federationExchangeStatusResponse = () =>
     return yield* _(jsonResponse(makeFederationExchangeStatus(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation actor JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub actor document response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationActorDocument, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the actor id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD Person document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
+export const federationActorDocumentResponse = () =>
+  Effect.gen(function*(_) {
+    const request = yield* _(HttpServerRequest.HttpServerRequest)
+    const context = yield* _(resolveFederationContext(request))
+    return yield* _(jsonLdResponse(makeFederationActorDocument(context), 200))
+  }).pipe(Effect.catchAll(errorResponse))
+
+/**
+ * Builds the federation outbox JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub outbox collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationOutboxCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the outbox id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
+export const federationOutboxDocumentResponse = () =>
+  Effect.gen(function*(_) {
+    const request = yield* _(HttpServerRequest.HttpServerRequest)
+    const context = yield* _(resolveFederationContext(request))
+    return yield* _(jsonLdResponse(makeFederationOutboxCollection(context), 200))
+  }).pipe(Effect.catchAll(errorResponse))
+
+/**
+ * Builds the federation followers JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub followers collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationFollowersCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the followers id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
+export const federationFollowersDocumentResponse = () =>
+  Effect.gen(function*(_) {
+    const request = yield* _(HttpServerRequest.HttpServerRequest)
+    const context = yield* _(resolveFederationContext(request))
+    return yield* _(jsonLdResponse(makeFederationFollowersCollection(context), 200))
+  }).pipe(Effect.catchAll(errorResponse))
+
+/**
+ * Builds the federation following JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub following collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationFollowingCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the following id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
+export const federationFollowingDocumentResponse = () =>
+  Effect.gen(function*(_) {
+    const request = yield* _(HttpServerRequest.HttpServerRequest)
+    const context = yield* _(resolveFederationContext(request))
+    return yield* _(jsonLdResponse(makeFederationFollowingCollection(context), 200))
+  }).pipe(Effect.catchAll(errorResponse))
+
+/**
+ * Builds the federation liked JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub liked collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationLikedCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the liked collection id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
+export const federationLikedDocumentResponse = () =>
+  Effect.gen(function*(_) {
+    const request = yield* _(HttpServerRequest.HttpServerRequest)
+    const context = yield* _(resolveFederationContext(request))
+    return yield* _(jsonLdResponse(makeFederationLikedCollection(context), 200))
+  }).pipe(Effect.catchAll(errorResponse))
+
 const terminalWebSocketUpgradeResponse = Effect.gen(function*(_) {
   const request = yield* _(HttpServerRequest.HttpServerRequest)
   const upgrade = readHeader(request, "upgrade")?.toLowerCase()
@@ -859,43 +974,23 @@ export const makeRouter = () => {
     ),
     HttpRouter.get(
       "/federation/actor",
-      Effect.gen(function*(_) {
-        const request = yield* _(HttpServerRequest.HttpServerRequest)
-        const context = yield* _(resolveFederationContext(request))
-        return yield* _(activityJsonResponse(makeFederationActorDocument(context), 200))
-      }).pipe(Effect.catchAll(errorResponse))
+      federationActorDocumentResponse()
     ),
     HttpRouter.get(
       "/federation/outbox",
-      Effect.gen(function*(_) {
-        const request = yield* _(HttpServerRequest.HttpServerRequest)
-        const context = yield* _(resolveFederationContext(request))
-        return yield* _(activityJsonResponse(makeFederationOutboxCollection(context), 200))
-      }).pipe(Effect.catchAll(errorResponse))
+      federationOutboxDocumentResponse()
     ),
     HttpRouter.get(
       "/federation/followers",
-      Effect.gen(function*(_) {
-        const request = yield* _(HttpServerRequest.HttpServerRequest)
-        const context = yield* _(resolveFederationContext(request))
-        return yield* _(activityJsonResponse(makeFederationFollowersCollection(context), 200))
-      }).pipe(Effect.catchAll(errorResponse))
+      federationFollowersDocumentResponse()
     ),
     HttpRouter.get(
       "/federation/following",
-      Effect.gen(function*(_) {
-        const request = yield* _(HttpServerRequest.HttpServerRequest)
-        const context = yield* _(resolveFederationContext(request))
-        return yield* _(activityJsonResponse(makeFederationFollowingCollection(context), 200))
-      }).pipe(Effect.catchAll(errorResponse))
+      federationFollowingDocumentResponse()
     ),
     HttpRouter.get(
       "/federation/liked",
-      Effect.gen(function*(_) {
-        const request = yield* _(HttpServerRequest.HttpServerRequest)
-        const context = yield* _(resolveFederationContext(request))
-        return yield* _(activityJsonResponse(makeFederationLikedCollection(context), 200))
-      }).pipe(Effect.catchAll(errorResponse))
+      federationLikedDocumentResponse()
     ),
     HttpRouter.get(
       "/federation/status",