@fedify/fedify 2.0.0-dev.1566 → 2.0.0-dev.159

package/dist/otel/mod.d.ts

@@ -0,0 +1,232 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { URLPattern } from "urlpattern-polyfill";
+import { KvKey, KvStore } from "../kv-CtOmTRNc.js";
+import { ExportResultCode } from "@opentelemetry/core";
+import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+
+//#region src/otel/exporter.d.ts
+/**
+ * The direction of an activity in the trace.
+ *
+ * @since 1.10.0
+ */
+type ActivityDirection = "inbound" | "outbound";
+/**
+ * Signature verification details for an inbound activity.
+ *
+ * @since 1.10.0
+ */
+interface SignatureVerificationDetails {
+  /**
+   * Whether HTTP Signatures were verified.
+   */
+  httpSignaturesVerified: boolean;
+  /**
+   * The key ID used for HTTP signature verification, if available.
+   */
+  httpSignaturesKeyId?: string;
+  /**
+   * Whether Linked Data Signatures were verified.
+   */
+  ldSignaturesVerified: boolean;
+}
+/**
+ * A record of an activity captured from a trace span.
+ * This interface stores the activity data along with trace context
+ * for distributed tracing support.
+ *
+ * @since 1.10.0
+ */
+interface TraceActivityRecord {
+  /**
+   * The trace ID from OpenTelemetry.
+   */
+  traceId: string;
+  /**
+   * The span ID from OpenTelemetry.
+   */
+  spanId: string;
+  /**
+   * The parent span ID, if any.
+   */
+  parentSpanId?: string;
+  /**
+   * Whether this is an inbound or outbound activity.
+   */
+  direction: ActivityDirection;
+  /**
+   * The ActivityPub activity type (e.g., "Create", "Follow", "Like").
+   */
+  activityType: string;
+  /**
+   * The activity's ID URL, if present.
+   */
+  activityId?: string;
+  /**
+   * The actor ID URL (sender of the activity).
+   */
+  actorId?: string;
+  /**
+   * The full JSON representation of the activity.
+   */
+  activityJson: string;
+  /**
+   * Whether the activity was verified (for inbound activities).
+   */
+  verified?: boolean;
+  /**
+   * Detailed signature verification information (for inbound activities).
+   */
+  signatureDetails?: SignatureVerificationDetails;
+  /**
+   * The timestamp when this record was created (ISO 8601 format).
+   */
+  timestamp: string;
+  /**
+   * The target inbox URL (for outbound activities).
+   */
+  inboxUrl?: string;
+}
+/**
+ * Summary information about a trace.
+ *
+ * @since 1.10.0
+ */
+interface TraceSummary {
+  /**
+   * The trace ID.
+   */
+  traceId: string;
+  /**
+   * The timestamp of the first activity in the trace.
+   */
+  timestamp: string;
+  /**
+   * The number of activities in the trace.
+   */
+  activityCount: number;
+  /**
+   * Activity types present in this trace.
+   */
+  activityTypes: string[];
+}
+/**
+ * Options for configuring the {@link FedifySpanExporter}.
+ *
+ * @since 1.10.0
+ */
+interface FedifySpanExporterOptions {
+  /**
+   * The time-to-live for stored trace data.
+   * If not specified, data will be stored indefinitely
+   * (or until manually deleted).
+   */
+  ttl?: Temporal.Duration;
+  /**
+   * The key prefix for storing trace data in the KvStore.
+   * Defaults to `["fedify", "traces"]`.
+   */
+  keyPrefix?: KvKey;
+}
+/**
+ * Options for the {@link FedifySpanExporter.getRecentTraces} method.
+ *
+ * @since 1.10.0
+ */
+interface GetRecentTracesOptions {
+  /**
+   * Maximum number of traces to return.
+   * If not specified, returns all available traces.
+   */
+  limit?: number;
+}
+/**
+ * A SpanExporter that persists ActivityPub activity traces to a
+ * {@link KvStore}.  This enables distributed tracing across multiple
+ * nodes in a Fedify deployment.
+ *
+ * The exporter captures activity data from OpenTelemetry span events
+ * (`activitypub.activity.received` and `activitypub.activity.sent`)
+ * and stores them in the KvStore with trace context preserved.
+ *
+ * @example Basic usage with MemoryKvStore
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ * import {
+ *   BasicTracerProvider,
+ *   SimpleSpanProcessor,
+ * } from "@opentelemetry/sdk-trace-base";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv, {
+ *   ttl: Temporal.Duration.from({ hours: 1 }),
+ * });
+ *
+ * const provider = new BasicTracerProvider({
+ *   spanProcessors: [new SimpleSpanProcessor(exporter)],
+ * });
+ * ```
+ *
+ * @example Querying stored traces
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv);
+ * const traceId = "abc123";
+ *
+ * // Get all activities for a specific trace
+ * const activities = await exporter.getActivitiesByTraceId(traceId);
+ *
+ * // Get recent traces
+ * const recentTraces = await exporter.getRecentTraces({ limit: 100 });
+ * ```
+ *
+ * @since 1.10.0
+ */
+declare class FedifySpanExporter implements SpanExporter {
+  #private;
+  /**
+   * Creates a new FedifySpanExporter.
+   *
+   * @param kv The KvStore to persist trace data to.
+   * @param options Configuration options.
+   */
+  constructor(kv: KvStore, options?: FedifySpanExporterOptions);
+  /**
+   * Exports spans to the KvStore.
+   *
+   * @param spans The spans to export.
+   * @param resultCallback Callback to invoke with the export result.
+   */
+  export(spans: ReadableSpan[], resultCallback: (result: {
+    code: ExportResultCode;
+  }) => void): void;
+  /**
+   * Gets all activity records for a specific trace ID.
+   *
+   * @param traceId The trace ID to query.
+   * @returns An array of activity records belonging to the trace.
+   */
+  getActivitiesByTraceId(traceId: string): Promise<TraceActivityRecord[]>;
+  /**
+   * Gets recent traces with summary information.
+   *
+   * @param options Options for the query.
+   * @returns An array of trace summaries.
+   */
+  getRecentTraces(options?: GetRecentTracesOptions): Promise<TraceSummary[]>;
+  /**
+   * Forces the exporter to flush any buffered data.
+   * This is a no-op because we write directly to the KvStore without buffering.
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Shuts down the exporter.
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { ActivityDirection, FedifySpanExporter, FedifySpanExporterOptions, GetRecentTracesOptions, SignatureVerificationDetails, TraceActivityRecord, TraceSummary };

package/dist/otel/mod.js

@@ -0,0 +1,261 @@
+
+          import { Temporal } from "@js-temporal/polyfill";
+          import { URLPattern } from "urlpattern-polyfill";
+        
+import { getLogger } from "@logtape/logtape";
+import { ExportResultCode } from "@opentelemetry/core";
+
+//#region src/otel/exporter.ts
+/**
+* A SpanExporter that persists ActivityPub activity traces to a
+* {@link KvStore}.  This enables distributed tracing across multiple
+* nodes in a Fedify deployment.
+*
+* The exporter captures activity data from OpenTelemetry span events
+* (`activitypub.activity.received` and `activitypub.activity.sent`)
+* and stores them in the KvStore with trace context preserved.
+*
+* @example Basic usage with MemoryKvStore
+* ```typescript ignore
+* import { MemoryKvStore } from "@fedify/fedify";
+* import { FedifySpanExporter } from "@fedify/fedify/otel";
+* import {
+*   BasicTracerProvider,
+*   SimpleSpanProcessor,
+* } from "@opentelemetry/sdk-trace-base";
+*
+* const kv = new MemoryKvStore();
+* const exporter = new FedifySpanExporter(kv, {
+*   ttl: Temporal.Duration.from({ hours: 1 }),
+* });
+*
+* const provider = new BasicTracerProvider({
+*   spanProcessors: [new SimpleSpanProcessor(exporter)],
+* });
+* ```
+*
+* @example Querying stored traces
+* ```typescript ignore
+* import { MemoryKvStore } from "@fedify/fedify";
+* import { FedifySpanExporter } from "@fedify/fedify/otel";
+*
+* const kv = new MemoryKvStore();
+* const exporter = new FedifySpanExporter(kv);
+* const traceId = "abc123";
+*
+* // Get all activities for a specific trace
+* const activities = await exporter.getActivitiesByTraceId(traceId);
+*
+* // Get recent traces
+* const recentTraces = await exporter.getRecentTraces({ limit: 100 });
+* ```
+*
+* @since 1.10.0
+*/
+var FedifySpanExporter = class {
+	#kv;
+	#ttl;
+	#keyPrefix;
+	/**
+	* Creates a new FedifySpanExporter.
+	*
+	* @param kv The KvStore to persist trace data to.
+	* @param options Configuration options.
+	*/
+	constructor(kv, options) {
+		this.#kv = kv;
+		this.#ttl = options?.ttl;
+		this.#keyPrefix = options?.keyPrefix ?? ["fedify", "traces"];
+	}
+	/**
+	* Exports spans to the KvStore.
+	*
+	* @param spans The spans to export.
+	* @param resultCallback Callback to invoke with the export result.
+	*/
+	export(spans, resultCallback) {
+		this.#exportAsync(spans).then(() => resultCallback({ code: ExportResultCode.SUCCESS })).catch((error) => {
+			getLogger([
+				"fedify",
+				"otel",
+				"exporter"
+			]).error("Failed to export spans to KvStore: {error}", { error });
+			resultCallback({ code: ExportResultCode.FAILED });
+		});
+	}
+	async #exportAsync(spans) {
+		const storeOperations = [];
+		for (const span of spans) {
+			const records = this.#extractRecords(span);
+			for (const record of records) storeOperations.push(this.#storeRecord(record));
+		}
+		const results = await Promise.allSettled(storeOperations);
+		const rejected = results.filter((r) => r.status === "rejected");
+		if (rejected.length > 0) throw new AggregateError(rejected.map((r) => r.reason), "Failed to store one or more trace activity records.");
+	}
+	#extractRecords(span) {
+		const records = [];
+		const spanContext = span.spanContext();
+		const traceId = spanContext.traceId;
+		const spanId = spanContext.spanId;
+		const parentSpanId = span.parentSpanContext?.spanId;
+		for (const event of span.events) if (event.name === "activitypub.activity.received") {
+			const record = this.#extractInboundRecord(event, traceId, spanId, parentSpanId);
+			if (record != null) records.push(record);
+		} else if (event.name === "activitypub.activity.sent") {
+			const record = this.#extractOutboundRecord(event, traceId, spanId, parentSpanId);
+			if (record != null) records.push(record);
+		}
+		return records;
+	}
+	#extractInboundRecord(event, traceId, spanId, parentSpanId) {
+		const attrs = event.attributes;
+		if (attrs == null) return null;
+		const activityJson = attrs["activitypub.activity.json"];
+		if (typeof activityJson !== "string") return null;
+		let activityType = "Unknown";
+		let activityId;
+		let actorId;
+		try {
+			const activity = JSON.parse(activityJson);
+			activityType = activity.type ?? "Unknown";
+			activityId = activity.id;
+			if (typeof activity.actor === "string") actorId = activity.actor;
+			else if (activity.actor != null && typeof activity.actor.id === "string") actorId = activity.actor.id;
+		} catch {}
+		const verified = attrs["activitypub.activity.verified"];
+		const httpSigVerified = attrs["http_signatures.verified"];
+		const httpSigKeyId = attrs["http_signatures.key_id"];
+		const ldSigVerified = attrs["ld_signatures.verified"];
+		let signatureDetails;
+		if (typeof httpSigVerified === "boolean" || typeof ldSigVerified === "boolean") signatureDetails = {
+			httpSignaturesVerified: httpSigVerified === true,
+			httpSignaturesKeyId: typeof httpSigKeyId === "string" && httpSigKeyId !== "" ? httpSigKeyId : void 0,
+			ldSignaturesVerified: ldSigVerified === true
+		};
+		return {
+			traceId,
+			spanId,
+			parentSpanId,
+			direction: "inbound",
+			activityType,
+			activityId,
+			actorId,
+			activityJson,
+			verified: typeof verified === "boolean" ? verified : void 0,
+			signatureDetails,
+			timestamp: (/* @__PURE__ */ new Date(event.time[0] * 1e3 + event.time[1] / 1e6)).toISOString()
+		};
+	}
+	#extractOutboundRecord(event, traceId, spanId, parentSpanId) {
+		const attrs = event.attributes;
+		if (attrs == null) return null;
+		const activityJson = attrs["activitypub.activity.json"];
+		if (typeof activityJson !== "string") return null;
+		let activityType = "Unknown";
+		let activityId;
+		let actorId;
+		try {
+			const activity = JSON.parse(activityJson);
+			activityType = activity.type ?? "Unknown";
+			activityId = activity.id;
+			if (typeof activity.actor === "string") actorId = activity.actor;
+			else if (activity.actor != null && typeof activity.actor.id === "string") actorId = activity.actor.id;
+		} catch {}
+		const inboxUrl = attrs["activitypub.inbox.url"];
+		const explicitActivityId = attrs["activitypub.activity.id"];
+		return {
+			traceId,
+			spanId,
+			parentSpanId,
+			direction: "outbound",
+			activityType,
+			activityId: activityId ?? (typeof explicitActivityId === "string" && explicitActivityId !== "" ? explicitActivityId : void 0),
+			actorId,
+			activityJson,
+			timestamp: (/* @__PURE__ */ new Date(event.time[0] * 1e3 + event.time[1] / 1e6)).toISOString(),
+			inboxUrl: typeof inboxUrl === "string" ? inboxUrl : void 0
+		};
+	}
+	async #storeRecord(record) {
+		const options = this.#ttl != null ? { ttl: this.#ttl } : void 0;
+		const key = [
+			...this.#keyPrefix,
+			record.traceId,
+			record.spanId
+		];
+		await this.#kv.set(key, record, options);
+		await this.#updateTraceSummary(record, options);
+	}
+	async #setWithCasRetry(key, transform, options) {
+		if (this.#kv.cas != null) for (let attempt = 0; attempt < 3; attempt++) {
+			const existing$1 = await this.#kv.get(key);
+			const newValue$1 = transform(existing$1);
+			if (await this.#kv.cas(key, existing$1, newValue$1, options)) return;
+		}
+		const existing = await this.#kv.get(key);
+		const newValue = transform(existing);
+		await this.#kv.set(key, newValue, options);
+	}
+	async #updateTraceSummary(record, options) {
+		const summaryKey = [
+			...this.#keyPrefix,
+			"_summaries",
+			record.traceId
+		];
+		await this.#setWithCasRetry(summaryKey, (existing) => {
+			const summary = existing != null ? {
+				traceId: existing.traceId,
+				timestamp: existing.timestamp,
+				activityCount: existing.activityCount,
+				activityTypes: [...existing.activityTypes]
+			} : {
+				traceId: record.traceId,
+				timestamp: record.timestamp,
+				activityCount: 0,
+				activityTypes: []
+			};
+			summary.activityCount += 1;
+			if (!summary.activityTypes.includes(record.activityType)) summary.activityTypes.push(record.activityType);
+			return summary;
+		}, options);
+	}
+	/**
+	* Gets all activity records for a specific trace ID.
+	*
+	* @param traceId The trace ID to query.
+	* @returns An array of activity records belonging to the trace.
+	*/
+	async getActivitiesByTraceId(traceId) {
+		const prefix = [...this.#keyPrefix, traceId];
+		const records = [];
+		for await (const entry of this.#kv.list(prefix)) records.push(entry.value);
+		return records;
+	}
+	/**
+	* Gets recent traces with summary information.
+	*
+	* @param options Options for the query.
+	* @returns An array of trace summaries.
+	*/
+	async getRecentTraces(options) {
+		const summaryPrefix = [...this.#keyPrefix, "_summaries"];
+		const summaries = [];
+		for await (const entry of this.#kv.list(summaryPrefix)) summaries.push(entry.value);
+		summaries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+		if (options?.limit != null) return summaries.slice(0, options.limit);
+		return summaries;
+	}
+	/**
+	* Forces the exporter to flush any buffered data.
+	* This is a no-op because we write directly to the KvStore without buffering.
+	*/
+	async forceFlush() {}
+	/**
+	* Shuts down the exporter.
+	*/
+	async shutdown() {}
+};
+
+//#endregion
+export { FedifySpanExporter };

package/dist/{owner-CQPnQVtf.d.ts → owner-BgI8C-VY.d.ts}

@@ -1,9 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { URLPattern } from "urlpattern-polyfill";
-import { DocumentLoader } from "./docloader-CxWcuWqQ.js";
-import { Activity, CryptographicKey } from "./vocab-SOE1ifCr.js";
-import { Actor } from "./actor-C22bXuuC.js";
+import { Activity, Actor, CryptographicKey } from "@fedify/vocab";
 import { TracerProvider } from "@opentelemetry/api";
+import { DocumentLoader } from "@fedify/vocab-runtime";
 
 //#region src/sig/owner.d.ts
 /**

package/dist/owner-C-zfmVAD.d.cts

@@ -0,0 +1,66 @@
+import { Activity, Actor, CryptographicKey } from "@fedify/vocab";
+import { DocumentLoader } from "@fedify/vocab-runtime";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/sig/owner.d.ts
+/**
+ * Options for {@link doesActorOwnKey}.
+ * @since 0.8.0
+ */
+interface DoesActorOwnKeyOptions {
+  /**
+   * The document loader to use for fetching the actor.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader to use for JSON-LD context retrieval.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The OpenTelemetry tracer provider to use for tracing.  If omitted,
+   * the global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Checks if the actor of the given activity owns the specified key.
+ * @param activity The activity to check.
+ * @param key The public key to check.
+ * @param options Options for checking the key ownership.
+ * @returns Whether the actor is the owner of the key.
+ */
+declare function doesActorOwnKey(activity: Activity, key: CryptographicKey, options: DoesActorOwnKeyOptions): Promise<boolean>;
+/**
+ * Options for {@link getKeyOwner}.
+ * @since 0.8.0
+ */
+interface GetKeyOwnerOptions {
+  /**
+   * The document loader to use for fetching the key and its owner.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader to use for JSON-LD context retrieval.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The OpenTelemetry tracer provider to use for tracing.  If omitted,
+   * the global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Gets the actor that owns the specified key.  Returns `null` if the key has no
+ * known owner.
+ *
+ * @param keyId The ID of the key to check, or the key itself.
+ * @param options Options for getting the key owner.
+ * @returns The actor that owns the key, or `null` if the key has no known
+ *          owner.
+ * @since 0.7.0
+ */
+declare function getKeyOwner(keyId: URL | CryptographicKey, options: GetKeyOwnerOptions): Promise<Actor | null>;
+//#endregion
+export { DoesActorOwnKeyOptions, GetKeyOwnerOptions, doesActorOwnKey, getKeyOwner };

package/dist/{owner-DZ5zP8JS.js → owner-CCSlDz_P.js}

@@ -3,9 +3,10 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { CryptographicKey, Object as Object$1, getDocumentLoader } from "./type-B7_rMIU9.js";
-import { isActor } from "./actor-DI_YpFlI.js";
-import { trace } from "@opentelemetry/api";
+import { deno_default } from "./deno-CGe3r5lB.js";
+import { CryptographicKey, Object as Object$1, isActor } from "@fedify/vocab";
+import { getDocumentLoader } from "@fedify/vocab-runtime";
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 
 //#region src/sig/owner.ts
 /**
@@ -16,11 +17,47 @@ import { trace } from "@opentelemetry/api";
 * @returns Whether the actor is the owner of the key.
 */
 async function doesActorOwnKey(activity, key, options) {
-	if (key.ownerId != null) return key.ownerId.href === activity.actorId?.href;
-	const actor = await activity.getActor(options);
-	if (actor == null || !isActor(actor)) return false;
-	for (const publicKeyId of actor.publicKeyIds) if (key.id != null && publicKeyId.href === key.id.href) return true;
-	return false;
+	const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+	const tracer = tracerProvider.getTracer(deno_default.name, deno_default.version);
+	return await tracer.startActiveSpan("activitypub.verify_key_ownership", {
+		kind: SpanKind.INTERNAL,
+		attributes: {
+			"activitypub.actor.id": activity.actorId?.href ?? "",
+			"activitypub.key.id": key.id?.href ?? ""
+		}
+	}, async (span) => {
+		try {
+			if (key.ownerId != null) {
+				const owns = key.ownerId.href === activity.actorId?.href;
+				span.setAttribute("activitypub.key_ownership.verified", owns);
+				span.setAttribute("activitypub.key_ownership.method", "owner_id");
+				return owns;
+			}
+			const actor = await activity.getActor(options);
+			if (actor == null || !isActor(actor)) {
+				span.setAttribute("activitypub.key_ownership.verified", false);
+				span.setAttribute("activitypub.key_ownership.method", "actor_fetch");
+				return false;
+			}
+			for (const publicKeyId of actor.publicKeyIds) if (key.id != null && publicKeyId.href === key.id.href) {
+				span.setAttribute("activitypub.key_ownership.verified", true);
+				span.setAttribute("activitypub.key_ownership.method", "actor_fetch");
+				return true;
+			}
+			span.setAttribute("activitypub.key_ownership.verified", false);
+			span.setAttribute("activitypub.key_ownership.method", "actor_fetch");
+			return false;
+		} catch (error) {
+			span.recordException(error);
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: String(error)
+			});
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
 }
 /**
 * Gets the actor that owns the specified key.  Returns `null` if the key has no