@fedify/fedify 2.4.0-dev.2253 → 2.4.0-dev.2259

package/dist/testing/mod.d.mts

@@ -2,7 +2,7 @@ import { Temporal } from "temporal-polyfill";
 import { URLPattern } from "urlpattern-polyfill";
 import { ExportResultCode } from "@opentelemetry/core";
 import { Router } from "@fedify/uri-template";
-import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Note, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
+import { Activity, Actor, Collection, CryptographicKey, DataIntegrityProof, Hashtag, Link, LookupObjectOptions, Multikey, Note, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
 import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 import { AuthenticatedDocumentLoaderFactory, DocumentLoader, DocumentLoaderFactory, GetUserAgentOptions, PortableObjectVerifier } from "@fedify/vocab-runtime";
@@ -169,6 +169,215 @@ interface GetNodeInfoOptions {
   userAgent?: GetUserAgentOptions | string;
 }
 //#endregion
+//#region src/sig/proof.d.ts
+/**
+ * The reason why {@link verifyPortableObjectProof} could not verify a portable
+ * object proof.
+ * @since 2.4.0
+ */
+type VerifyPortableObjectProofFailureReason = {
+  /**
+   * The document has neither a portable `ap:` or `ap+ef61:` ID nor an
+   * FEP-ef61 compatible identifier.
+   */
+  readonly type: "notPortableObject";
+} | {
+  /**
+   * The document is a portable collection without an Object Integrity
+   * Proof.  Its trust policy is outside this verifier.
+   */
+  readonly type: "unsecuredCollection";
+} | {
+  /** The portable document is a core type outside FEP-ef61 proof policy. */readonly type: "unsupportedObjectType"; /** The FEP-2277 core type of the document. */
+  readonly objectType: "verificationMethod" | "publicKey" | "link";
+} | {
+  /** A portable actor, activity, or object has no proof. */readonly type: "missingProof";
+} | {
+  /**
+   * A portable actor's `gateways` is missing or empty, or has an item that
+   * is not an HTTP(S) URI with an empty path, query, and fragment.
+   * The document is rejected before its proofs are verified, so this
+   * reason does not mean that the proofs are valid.
+   */
+  readonly type: "invalidGateways";
+} | {
+  /** The proof is malformed, unsupported, or cryptographically invalid. */readonly type: "invalidProof"; /** The zero-based index of the invalid proof. */
+  readonly proofIndex: number;
+} | {
+  /** The proof's verification method is not a valid DID URL. */readonly type: "unsupportedVerificationMethod"; /** The zero-based index of the proof. */
+  readonly proofIndex: number; /** The unsupported verification method. */
+  readonly verificationMethod: URL;
+} | {
+  /** The verification method DID does not match the portable ID authority. */readonly type: "verificationMethodMismatch"; /** The zero-based index of the proof. */
+  readonly proofIndex: number; /** The portable object ID. */
+  readonly objectId: URL; /** The mismatching verification method. */
+  readonly verificationMethod: URL;
+};
+//#endregion
+//#region src/sig/compound-proof.d.ts
+/** Why compound-proof discovery could not produce an atomic result. */
+type CompoundProofDiscoveryFailureReason = {
+  readonly type: "invalidJsonTree";
+  readonly path: string;
+} | {
+  readonly type: "unsupportedProofShape";
+  readonly path: string;
+} | {
+  readonly type: "limitExceeded";
+  readonly limit: "depth" | "maps" | "proofs" | "bytes";
+  readonly maximum: number;
+  readonly actual: number;
+  readonly path: string;
+};
+/** Why a discovered map-local proof did not verify. */
+type CompoundProofVerificationFailureReason = {
+  /** A nested secured map does not carry its own JSON-LD context. */readonly type: "missingContext";
+} | {
+  /** The direct proof is malformed, unsupported, or invalid. */readonly type: "invalidProof";
+};
+/** Why one portable map did not pass compound proof policy. */
+type CompoundPortableObjectFailureReason = CompoundProofVerificationFailureReason | VerifyPortableObjectProofFailureReason | {
+  /** The portable map could not be interpreted by the policy layer. */readonly type: "invalidPortableObject";
+};
+//#endregion
+//#region src/sig/http.d.ts
+/**
+ * The standard to use for signing and verifying HTTP signatures.
+ * @since 1.6.0
+ */
+type HttpMessageSignaturesSpec =
+/**
+ * The Signing HTTP Messages (draft-cavage-http-signatures-12) specification,
+ * which is widely adopted and used in the fediverse (as of May 2025).
+ */
+"draft-cavage-http-signatures-12"
+/**
+ * The HTTP Message Signatures (RFC 9421) specification, which is the
+ * finalized standard but not widely adopted yet (as of May 2025).
+ */
+| "rfc9421";
+/**
+ * The reason why {@link verifyRequestDetailed} could not verify a request.
+ * @since 2.1.0
+ */
+type VerifyRequestFailureReason = {
+  readonly type: "keyFetchError";
+  readonly keyId: URL;
+  readonly result: FetchKeyErrorResult;
+} | {
+  readonly type: "invalidSignature";
+  readonly keyId?: URL;
+} | {
+  readonly type: "noSignature";
+};
+//#endregion
+//#region src/sig/verification.d.ts
+/**
+ * A snapshot of a key actually used to check a signature.
+ * @since 2.4.0
+ */
+type InboxVerificationKey = {
+  readonly type: "cryptographicKey";
+  readonly id: URL | null;
+  readonly ownerId: URL | null;
+  readonly publicKey: CryptoKey;
+} | {
+  readonly type: "multikey";
+  readonly id: URL | null;
+  readonly controllerId: URL | null;
+  readonly publicKey: CryptoKey;
+};
+/**
+ * Why a cryptographic check failed.
+ * @since 2.4.0
+ */
+type InboxSignatureFailureReason = {
+  readonly type: "invalidSignature";
+} | {
+  readonly type: "keyFetchError";
+  readonly keyId: URL;
+  readonly result: FetchKeyErrorResult;
+};
+/**
+ * The signature or proof being checked.
+ * @since 2.4.0
+ */
+type InboxSignatureIdentity = {
+  readonly mechanism: "http";
+  readonly spec: HttpMessageSignaturesSpec;
+  readonly label: string | null;
+} | {
+  readonly mechanism: "linkedData";
+} | {
+  readonly mechanism: "objectIntegrity";
+  readonly proofId: string | null; /** Index within this evaluation, not a global proof identifier. */
+  readonly proofIndex: number | null;
+};
+/**
+ * Evidence from one signature/proof, including cached-key retries.
+ * @since 2.4.0
+ */
+type InboxSignatureCheck = InboxSignatureIdentity & {
+  /** The declaration as received, including invalid IRIs. */readonly declaredKeyId: string | null; /** Keys actually tried, in use order; refresh details are not a retry API. */
+  readonly triedKeys: readonly InboxVerificationKey[];
+} & ({
+  readonly status: "verified";
+  readonly key: InboxVerificationKey;
+} | {
+  readonly status: "rejected";
+  readonly reason: InboxSignatureFailureReason;
+} | {
+  readonly status: "error";
+  readonly error: unknown;
+});
+/**
+ * A bounded proof-policy diagnostic.
+ * @since 2.4.0
+ */
+type InboxProofPolicyFailureReason = VerifyPortableObjectProofFailureReason | CompoundPortableObjectFailureReason | CompoundProofDiscoveryFailureReason | {
+  readonly type: "invalidObjectId" | "invalidDocument" | "subjectMismatch";
+};
+/**
+ * Why a complete verification evaluation was rejected.
+ * @since 2.4.0
+ */
+type InboxVerificationFailureReason = {
+  readonly type: "noSignature";
+} | {
+  readonly type: "signatureVerificationFailed";
+} | {
+  readonly type: "uncoveredAttribution";
+  readonly attributionIds: readonly URL[];
+} | {
+  readonly type: "missingOwner";
+} | {
+  readonly type: "proofPolicy";
+  readonly reason: InboxProofPolicyFailureReason;
+};
+/**
+ * A logical verification evaluation, separate from inbox authentication.
+ * @since 2.4.0
+ */
+type InboxVerificationAttempt = {
+  readonly mechanism: "http" | "linkedData" | "objectIntegrity";
+  readonly subject: {
+    readonly id: URL | null; /** RFC 6901 pointer; empty for the root, null when unavailable. */
+    readonly pointer: string | null;
+  };
+  readonly checks: readonly InboxSignatureCheck[];
+} & ({
+  readonly status: "verified"; /** Direct references to successful members of checks. */
+  readonly signatures: readonly Extract<InboxSignatureCheck, {
+    status: "verified";
+  }>[];
+} | {
+  readonly status: "rejected";
+  readonly reason: InboxVerificationFailureReason;
+} | {
+  readonly status: "error";
+  readonly error: unknown;
+});
+//#endregion
 //#region src/sig/key.d.ts
 /**
  * Detailed fetch failure information from {@link fetchKeyDetailed}.
@@ -203,43 +412,111 @@ interface GetKeyOwnerOptions {
   tracerProvider?: TracerProvider;
 }
 //#endregion
-//#region src/compat/types.d.ts
+//#region src/federation/inbox-report.d.ts
 /**
- * A function that transforms an activity object.
- * @since 1.4.0
+ * A JSON value retained from the incoming request.
+ * @since 2.4.0
  */
-type ActivityTransformer<TContextData> = (activity: Activity, context: Context<TContextData>) => Activity;
-//#endregion
-//#region src/sig/http.d.ts
+type InboxJsonValue = null | boolean | number | string | readonly InboxJsonValue[] | {
+  readonly [key: string]: InboxJsonValue;
+};
 /**
- * The standard to use for signing and verifying HTTP signatures.
- * @since 1.6.0
+ * The final inbox authentication decision.
+ * @since 2.4.0
  */
-type HttpMessageSignaturesSpec =
+type InboxAuthentication = {
+  readonly status: "verified"; /** Direct references to the attempts that authenticated this delivery. */
+  readonly attempts: readonly Extract<InboxVerificationAttempt, {
+    status: "verified";
+  }>[];
+} | {
+  readonly status: "rejected";
+  readonly reason: {
+    readonly type: "verificationFailed";
+  } | {
+    readonly type: "actorKeyMismatch";
+    readonly key: InboxVerificationKey;
+    readonly actorIds: readonly URL[];
+  } | {
+    readonly type: "proofPolicy";
+    readonly policy: "portableActor" | "portableActivity" | "compound";
+    readonly detail?: InboxProofPolicyFailureReason;
+  } | {
+    readonly type: "invalidNonce";
+  };
+} | {
+  readonly status: "skipped";
+} | {
+  readonly status: "notDetermined";
+};
 /**
- * The Signing HTTP Messages (draft-cavage-http-signatures-12) specification,
- * which is widely adopted and used in the fediverse (as of May 2025).
+ * How an inbox request finished.
+ * @since 2.4.0
  */
-"draft-cavage-http-signatures-12"
+type InboxRequestOutcome = {
+  readonly type: "response";
+  readonly status: number;
+  readonly disposition: "processed" | "enqueued" | "duplicate" | "unhandled" | "customResponse";
+} | {
+  readonly type: "response";
+  readonly status: number;
+  readonly disposition: "rejected";
+  readonly reason: "recipientNotFound" | "invalidJson" | "invalidJsonLd" | "invalidActivity" | "bodyTooLarge" | "missingActor" | "authentication";
+} | {
+  readonly type: "response";
+  readonly status: number;
+  readonly disposition: "failed";
+  readonly reason: "bodyUnavailable" | "enqueueError" | "listenerError";
+  readonly error?: unknown;
+} | {
+  readonly type: "exception";
+  readonly stage: "prepare" | "parse" | "verify" | "policy" | "dispatch" | "respond"; /** The original thrown value, including null/undefined. */
+  readonly error: unknown;
+};
 /**
- * The HTTP Message Signatures (RFC 9421) specification, which is the
- * finalized standard but not widely adopted yet (as of May 2025).
+ * Observations of a single inbox delivery request.
+ * @since 2.4.0
  */
-| "rfc9421";
+interface InboxRequestReport {
+  /** The delivery route, including a portable gateway route. */
+  readonly inbox: {
+    readonly kind: "personal" | "shared" | "portable";
+    readonly recipient: string | null;
+  };
+  /** Unavailable differs from a successfully parsed JSON null. */
+  readonly payload: {
+    readonly status: "unavailable";
+  } | {
+    readonly status: "parsed";
+    readonly value: InboxJsonValue;
+  };
+  /** The Activity obtained by the normal processing flow, if any. */
+  readonly activity: Activity | null;
+  /** Logical evaluations, including unsuccessful fallback paths. */
+  readonly attempts: readonly InboxVerificationAttempt[];
+  /** Cryptographic success alone does not imply this decision is verified. */
+  readonly authentication: InboxAuthentication;
+  /** Response status snapshot or the original exception. */
+  readonly outcome: InboxRequestOutcome;
+}
 /**
- * The reason why {@link verifyRequestDetailed} could not verify a request.
- * @since 2.1.0
+ * Observes an inbox delivery after processing, before fetch resolves/rethrows.
+ * The callback is awaited.  Its errors are logged and swallowed, preserving
+ * the original response/exception.  The last registered callback replaces the
+ * previous one.  It excludes inbox collection GETs, unmatched routes,
+ * programmatic routing, and queue workers.  This is not an atomic persistence
+ * guarantee.  Keys/owner/controller declarations remain untrusted unless the
+ * final authentication decision verifies them.
+ * @since 2.4.0
  */
-type VerifyRequestFailureReason = {
-  readonly type: "keyFetchError";
-  readonly keyId: URL;
-  readonly result: FetchKeyErrorResult;
-} | {
-  readonly type: "invalidSignature";
-  readonly keyId?: URL;
-} | {
-  readonly type: "noSignature";
-};
+type InboxRequestFinishedHandler<TContextData> = (context: RequestContext<TContextData>, report: InboxRequestReport) => void | Promise<void>;
+//#endregion
+//#region src/compat/types.d.ts
+/**
+ * A function that transforms an activity object.
+ * @since 1.4.0
+ */
+type ActivityTransformer<TContextData> = (activity: Activity, context: Context<TContextData>) => Activity;
 //#endregion
 //#region src/federation/collection.d.ts
 /**
@@ -2755,6 +3032,16 @@ interface InboxListenerSetters<TContextData> {
    * @returns The setters object so that settings can be chained.
    */
   onError(handler: InboxErrorHandler<TContextData>): InboxListenerSetters<TContextData>;
+  /**
+   * Observes each configured inbox delivery once, before fetch finishes.
+   * The callback is awaited and its errors do not alter delivery processing.
+   * Calling this again replaces the previous callback.  Built federations
+   * retain the callback registered at build time.
+   * @param handler The request completion observer.
+   * @returns This setter for chaining.
+   * @since 2.4.0
+   */
+  onRequestFinished(handler: InboxRequestFinishedHandler<TContextData>): InboxListenerSetters<TContextData>;
   /**
    * Registers a callback for incoming activities whose HTTP signatures could
    * not be verified.

package/dist/utils/docloader.test.mjs

@@ -5,9 +5,9 @@ import { t as esm_default } from "../esm-BHXXx4Wx.mjs";
 import { t as assertEquals } from "../assert_equals-Z6IcEbWU.mjs";
 import "../std__assert-DvMDRPes.mjs";
 import { t as assertRejects } from "../assert_rejects-CTptdYck.mjs";
-import { f as verifyRequest } from "../http-CUyBaVsQ.mjs";
+import { f as verifyRequest } from "../http-BqSbUEiQ.mjs";
 import { i as rsaPrivateKey2 } from "../keys-DIJNHW-Y.mjs";
-import { t as getAuthenticatedDocumentLoader } from "../docloader-fbmPhCdS.mjs";
+import { t as getAuthenticatedDocumentLoader } from "../docloader-CpdFLwAg.mjs";
 import { configure, reset } from "@logtape/logtape";
 import { FetchError, UrlError } from "@fedify/vocab-runtime";
 import { mockDocumentLoader, test } from "@fedify/fixture";

package/dist/utils/kv-cache.test.mjs

@@ -1,7 +1,7 @@
 import { Temporal } from "temporal-polyfill";
 import { URLPattern } from "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
-import { n as kvCache, t as MockKvStore } from "../kv-cache-Dmqd7s2a.mjs";
+import { n as kvCache, t as MockKvStore } from "../kv-cache-CWWlMv-s.mjs";
 import { preloadedContexts } from "@fedify/vocab-runtime";
 import { deepStrictEqual, throws } from "node:assert";
 import { createTestMeterProvider, mockDocumentLoader, test } from "@fedify/fixture";

package/dist/utils/mod.cjs

@@ -1,5 +1,5 @@
 const { URLPattern } = require("urlpattern-polyfill");
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_kv_cache = require("../kv-cache-BnWemxH2.cjs");
+const require_kv_cache = require("../kv-cache-D73yVcE5.cjs");
 exports.getAuthenticatedDocumentLoader = require_kv_cache.getAuthenticatedDocumentLoader;
 exports.kvCache = require_kv_cache.kvCache;

package/dist/utils/mod.d.cts

@@ -1,3 +1,3 @@
 /// <reference lib="esnext.temporal" />
-import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../mod-DFL6IxYQ.cjs";
+import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../mod-Dw-nPxQh.cjs";
 export { getAuthenticatedDocumentLoader, kvCache };

package/dist/utils/mod.d.ts

@@ -1,3 +1,3 @@
 /// <reference lib="esnext.temporal" />
-import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../mod-B8MI1mpi.js";
+import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../mod-DEZXwV6J.js";
 export { getAuthenticatedDocumentLoader, kvCache };

package/dist/utils/mod.js

@@ -1,4 +1,4 @@
 import { Temporal } from "temporal-polyfill";
 import { URLPattern } from "urlpattern-polyfill";
-import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../kv-cache-DhMzUXEE.js";
+import { n as getAuthenticatedDocumentLoader, t as kvCache } from "../kv-cache-J0v3UbUn.js";
 export { getAuthenticatedDocumentLoader, kvCache };

package/dist/verification-C3954hQh.mjs

@@ -0,0 +1,5 @@
+import "temporal-polyfill";
+import "urlpattern-polyfill";
+globalThis.addEventListener = () => {};
+import { a as verificationObservation, r as snapshotKey } from "./verification-Dpfcw8ml.mjs";
+export { snapshotKey, verificationObservation };

package/dist/verification-Dpfcw8ml.mjs

@@ -0,0 +1,105 @@
+import "temporal-polyfill";
+import "urlpattern-polyfill";
+globalThis.addEventListener = () => {};
+import { CryptographicKey } from "@fedify/vocab";
+//#region src/sig/verification.ts
+const verificationObservation = Symbol("verificationObservation");
+function snapshotKey(key) {
+	if (key.publicKey == null) throw new TypeError("Verification key has no public key.");
+	const id = key.id == null ? null : new URL(key.id.href);
+	return key instanceof CryptographicKey ? {
+		type: "cryptographicKey",
+		id,
+		ownerId: key.ownerId == null ? null : new URL(key.ownerId.href),
+		publicKey: key.publicKey
+	} : {
+		type: "multikey",
+		id,
+		controllerId: key.controllerId == null ? null : new URL(key.controllerId.href),
+		publicKey: key.publicKey
+	};
+}
+function triedKey(options, key) {
+	const check = options[verificationObservation]?.check;
+	if (check != null) check.triedKeys.push(snapshotKey(key));
+}
+async function observeCheck(options, identity, declaredKeyId, operation) {
+	const observation = options[verificationObservation];
+	if (observation?.attempt == null) return await operation(observation ?? { attempts: [] });
+	const check = {
+		identity,
+		declaredKeyId,
+		triedKeys: []
+	};
+	const base = {
+		...identity,
+		declaredKeyId,
+		triedKeys: check.triedKeys
+	};
+	try {
+		const key = await operation({
+			...observation,
+			check
+		});
+		observation.attempt.checks.push(key == null ? {
+			...base,
+			status: "rejected",
+			reason: check.reason ?? { type: "invalidSignature" }
+		} : {
+			...base,
+			status: "verified",
+			key: check.triedKeys.at(-1) ?? snapshotKey(key)
+		});
+		return key;
+	} catch (error) {
+		observation.attempt.checks.push({
+			...base,
+			status: "error",
+			error
+		});
+		throw error;
+	}
+}
+async function observeAttempt(options, mechanism, operation, isVerified) {
+	const observation = options[verificationObservation];
+	if (observation == null) return await operation({ attempts: [] });
+	const attempt = { checks: [] };
+	const base = {
+		mechanism,
+		subject: observation.subject == null ? {
+			id: null,
+			pointer: ""
+		} : {
+			id: observation.subject.id == null ? null : new URL(observation.subject.id.href),
+			pointer: observation.subject.pointer
+		},
+		checks: attempt.checks
+	};
+	try {
+		const value = await operation({
+			...observation,
+			subject: base.subject,
+			attempt,
+			check: void 0
+		});
+		observation.attempts.push(isVerified(value) ? {
+			...base,
+			status: "verified",
+			signatures: attempt.checks.filter((check) => check.status === "verified")
+		} : {
+			...base,
+			status: "rejected",
+			reason: attempt.reason ?? { type: "signatureVerificationFailed" }
+		});
+		return value;
+	} catch (error) {
+		observation.attempts.push({
+			...base,
+			status: "error",
+			error
+		});
+		throw error;
+	}
+}
+//#endregion
+export { verificationObservation as a, triedKey as i, observeCheck as n, snapshotKey as r, observeAttempt as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/fedify",
-  "version": "2.4.0-dev.2253+f5212c33",
+  "version": "2.4.0-dev.2259+d9c843fc",
   "description": "An ActivityPub server framework",
   "keywords": [
     "ActivityPub",
@@ -151,10 +151,10 @@
     "structured-field-values": "^2.0.4",
     "temporal-polyfill": "^1.0.1",
     "urlpattern-polyfill": "^10.1.0",
-    "@fedify/vocab-runtime": "2.4.0-dev.2253+f5212c33",
-    "@fedify/webfinger": "2.4.0-dev.2253+f5212c33",
-    "@fedify/vocab": "2.4.0-dev.2253+f5212c33",
-    "@fedify/uri-template": "2.4.0-dev.2253+f5212c33"
+    "@fedify/uri-template": "2.4.0-dev.2259+d9c843fc",
+    "@fedify/vocab-runtime": "2.4.0-dev.2259+d9c843fc",
+    "@fedify/webfinger": "2.4.0-dev.2259+d9c843fc",
+    "@fedify/vocab": "2.4.0-dev.2259+d9c843fc"
   },
   "devDependencies": {
     "@std/assert": "npm:@jsr/std__assert@^0.226.0",
@@ -167,7 +167,7 @@
     "typescript": "^6.0.0",
     "wrangler": "^4.17.0",
     "@fedify/fixture": "2.0.0",
-    "@fedify/vocab-tools": "^2.4.0-dev.2253+f5212c33"
+    "@fedify/vocab-tools": "^2.4.0-dev.2259+d9c843fc"
   },
   "scripts": {
     "build:self": "tsdown",