@fedify/fedify 2.0.0-dev.1604 → 2.0.0-dev.1690

package/dist/mod-CxkWO3Mg.d.cts

@@ -0,0 +1,307 @@
+import { DocumentLoader, GetUserAgentOptions } from "./docloader-D-MrRyHl.cjs";
+import { Collection, Link, Object as Object$1 } from "./vocab-Dw1-yVGg.cjs";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/vocab/lookup.d.ts
+/**
+ * Options for the {@link lookupObject} function.
+ *
+ * @since 0.2.0
+ */
+interface LookupObjectOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   * @since 0.8.0
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * Whether to allow fetching an object with an `@id` having a different
+   * origin than the object's URL.  This is not recommended, as it may
+   * lead to security issues.  Only use this option if you know what you
+   * are doing.
+   *
+   * How to handle the case when an object's `@id` has a different origin
+   * than the object's URL:
+   *
+   *  -  `"ignore"` (default): Do not return the object, and log a warning.
+   *  -  `"throw"`: Throw an error.
+   *  -  `"trust"`: Bypass the check and return the object anyway.  This
+   *     is not recommended, as it may lead to security issues.  Only use
+   *     this option if you know what you are doing.
+   *
+   * @since 1.9.0
+   */
+  crossOrigin?: "ignore" | "throw" | "trust";
+  /**
+   * The options for making `User-Agent` header.
+   * If a string is given, it is used as the `User-Agent` header value.
+   * If an object is given, it is passed to {@link getUserAgent} to generate
+   * the `User-Agent` header value.
+   * @since 1.3.0
+   */
+  userAgent?: GetUserAgentOptions | string;
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+  /**
+   * AbortSignal for cancelling the request.
+   * @since 1.8.0
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Looks up an ActivityStreams object by its URI (including `acct:` URIs)
+ * or a fediverse handle (e.g., `@user@server` or `user@server`).
+ *
+ * @example
+ * ``` typescript
+ * // Look up an actor by its fediverse handle:
+ * await lookupObject("@hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // A fediverse handle can omit the leading '@':
+ * await lookupObject("hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // A `acct:` URI can be used as well:
+ * await lookupObject("acct:hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // Look up an object by its URI:
+ * await lookupObject("https://todon.eu/@hongminhee/112060633798771581");
+ * // returning a `Note` object.
+ *
+ * // It can be a `URL` object as well:
+ * await lookupObject(new URL("https://todon.eu/@hongminhee/112060633798771581"));
+ * // returning a `Note` object.
+ * ```
+ *
+ * @param identifier The URI or fediverse handle to look up.
+ * @param options Lookup options.
+ * @returns The object, or `null` if not found.
+ * @since 0.2.0
+ */
+declare function lookupObject(identifier: string | URL, options?: LookupObjectOptions): Promise<Object$1 | null>;
+/**
+ * Options for the {@link traverseCollection} function.
+ * @since 1.1.0
+ */
+interface TraverseCollectionOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * Whether to suppress errors when fetching pages.  If `true`,
+   * errors will be logged but not thrown.  Defaults to `false`.
+   */
+  suppressError?: boolean;
+  /**
+   * The interval to wait between fetching pages.  Zero or negative
+   * values will disable the interval.  Disabled by default.
+   *
+   * @default `{ seconds: 0 }`
+   */
+  interval?: Temporal.Duration | Temporal.DurationLike;
+}
+/**
+ * Traverses a collection, yielding each item in the collection.
+ * If the collection is paginated, it will fetch the next page
+ * automatically.
+ *
+ * @example
+ * ``` typescript
+ * const collection = await lookupObject(collectionUrl);
+ * if (collection instanceof Collection) {
+ *   for await (const item of traverseCollection(collection)) {
+ *     console.log(item.id?.href);
+ *   }
+ * }
+ * ```
+ *
+ * @param collection The collection to traverse.
+ * @param options Options for traversing the collection.
+ * @returns An async iterable of each item in the collection.
+ * @since 1.1.0
+ */
+declare function traverseCollection(collection: Collection, options?: TraverseCollectionOptions): AsyncIterable<Object$1 | Link>;
+//#endregion
+//#region src/vocab/constants.d.ts
+/**
+ * The special public collection for [public addressing].  *Do not mutate this
+ * object.*
+ *
+ * [public addressing]: https://www.w3.org/TR/activitypub/#public-addressing
+ *
+ * @since 0.7.0
+ */
+declare const PUBLIC_COLLECTION: URL;
+//#endregion
+//#region src/vocab/handle.d.ts
+/**
+ * Represents a fediverse handle, which consists of a username and a host.
+ * The username can be alphanumeric and may include special characters,
+ * while the host is typically a domain name.
+ * @since 1.8.0
+ */
+interface FediverseHandle {
+  /**
+   * The username part of the fediverse handle.
+   * It can include alphanumeric characters and some special characters.
+   */
+  readonly username: string;
+  /**
+   * The host part of the fediverse handle, typically a domain name.
+   * It is the part after the `@` symbol in the handle.
+   */
+  readonly host: string;
+}
+/**
+ * Parses a fediverse handle in the format `@user@server` or `user@server`.
+ * The `user` part can contain alphanumeric characters and some special
+ * characters except `@`.  The `server` part is all characters after the `@`
+ * symbol in the middle.
+ *
+ * @example
+ * ```typescript
+ * const handle = parseFediverseHandle("@username@example.com");
+ * console.log(handle?.username); // "username"
+ * console.log(handle?.host);     // "example.com"
+ * ```
+ *
+ * @param handle - The fediverse handle string to parse.
+ * @returns A {@link FediverseHandle} object with `username` and `host`
+ *          if the input is valid; otherwise `null`.
+ * @since 1.8.0
+ */
+declare function parseFediverseHandle(handle: string): FediverseHandle | null;
+/**
+ * Checks if a string is a valid fediverse handle in the format `@user@server`
+ * or `user@server`.  The `user` part can contain alphanumeric characters and
+ * some special characters except `@`.  The `server` part is all characters
+ * after the `@` symbol in the middle.
+ *
+ * @example
+ * ```typescript
+ * console.log(isFediverseHandle("@username@example.com")); // true
+ * console.log(isFediverseHandle("username@example.com"));  // true
+ * console.log(isFediverseHandle("@username@"));            // false
+ * ```
+ *
+ * @param handle - The string to test as a fediverse handle.
+ * @returns `true` if the string matches the fediverse handle pattern;
+ *          otherwise `false`.
+ * @since 1.8.0
+ */
+declare function isFediverseHandle(handle: string): handle is `${string}@${string}`;
+/**
+ * Converts a fediverse handle in the format `@user@server` or `user@server`
+ * to an `acct:` URI, which is a URL-like identifier for ActivityPub actors.
+ *
+ * @example
+ * ```typescript
+ * const identifier = toAcctUrl("@username@example.com");
+ * console.log(identifier?.href); // "acct:username@example.com"
+ * ```
+ *
+ * @param handle - The fediverse handle string to convert.
+ * @returns A `URL` object representing the `acct:` URI if conversion succeeds;
+ *          otherwise `null`.
+ * @since 1.8.0
+ */
+declare function toAcctUrl(handle: string): URL | null;
+//#endregion
+//#region src/vocab/type.d.ts
+/**
+ * Returns the type URI of the given object.
+ *
+ * @example
+ * ``` typescript
+ * import { getTypeId, Person } from "@fedify/fedify";
+ *
+ * const obj = new Person({});
+ * console.log(getTypeId(obj));
+ * // => new URL("https://www.w3.org/ns/activitystreams#Person")
+ * ```
+ *
+ * @param object The Activity Vocabulary object.
+ * @returns The type URI of the object, e.g.,
+ *          `new URL("https://www.w3.org/ns/activitystreams#Person")`.
+ *          If the given `object` is `null` or `undefined`, returns `null` or
+ *          `undefined`, respectively.
+ * @since 1.3.0
+ */
+declare function getTypeId(object: Object$1 | Link): URL;
+/**
+ * Returns the type URI of the given object.
+ *
+ * @example
+ * ``` typescript
+ * import { getTypeId, Person } from "@fedify/fedify";
+ *
+ * const obj = new Person({});
+ * console.log(getTypeId(obj));
+ * // => new URL("https://www.w3.org/ns/activitystreams#Person")
+ * ```
+ *
+ * @param object The Activity Vocabulary object.
+ * @returns The type URI of the object, e.g.,
+ *          `new URL("https://www.w3.org/ns/activitystreams#Person")`.
+ *          If the given `object` is `null` or `undefined`, returns `null` or
+ *          `undefined`, respectively.
+ * @since 1.3.0
+ */
+declare function getTypeId(object: Object$1 | Link | undefined): URL | undefined;
+/**
+ * Returns the type URI of the given object.
+ *
+ * @example
+ * ``` typescript
+ * import { getTypeId, Person } from "@fedify/fedify";
+ *
+ * const obj = new Person({});
+ * console.log(getTypeId(obj));
+ * // => new URL("https://www.w3.org/ns/activitystreams#Person")
+ * ```
+ *
+ * @param object The Activity Vocabulary object.
+ * @returns The type URI of the object, e.g.,
+ *          `new URL("https://www.w3.org/ns/activitystreams#Person")`.
+ *          If the given `object` is `null` or `undefined`, returns `null` or
+ *          `undefined`, respectively.
+ * @since 1.3.0
+ */
+declare function getTypeId(object: Object$1 | Link | null): URL | null;
+/**
+ * Returns the type URI of the given object.
+ *
+ * @example
+ * ``` typescript
+ * import { getTypeId, Person } from "@fedify/fedify";
+ *
+ * const obj = new Person({});
+ * console.log(getTypeId(obj));
+ * // => new URL("https://www.w3.org/ns/activitystreams#Person")
+ * ```
+ *
+ * @param object The Activity Vocabulary object.
+ * @returns The type URI of the object, e.g.,
+ *          `new URL("https://www.w3.org/ns/activitystreams#Person")`.
+ *          If the given `object` is `null` or `undefined`, returns `null` or
+ *          `undefined`, respectively.
+ * @since 1.3.0
+ */
+declare function getTypeId(object: Object$1 | Link | null | undefined): URL | null | undefined;
+//#endregion
+export { FediverseHandle, LookupObjectOptions, PUBLIC_COLLECTION, TraverseCollectionOptions, getTypeId, isFediverseHandle, lookupObject, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/{mod-RI3-KvUI.d.ts → mod-D6hQoxC5.d.ts}

@@ -1,7 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { URLPattern } from "urlpattern-polyfill";
-import { Activity } from "./vocab-SOE1ifCr.js";
-import { ActivityTransformer, Context } from "./context-CDSZdQHD.js";
+import { Activity } from "./vocab-BI0Ak5lL.js";
+import { ActivityTransformer, Context } from "./context-ByZprN0S.js";
 
 //#region src/compat/transformers.d.ts
 

package/dist/mod-Djzcw2ry.d.cts

@@ -0,0 +1,266 @@
+import { DocumentLoader } from "./docloader-D-MrRyHl.cjs";
+import { CryptographicKey, DataIntegrityProof, Multikey, Object as Object$1 } from "./vocab-Dw1-yVGg.cjs";
+import { KeyCache } from "./http-D-e6AFwR.cjs";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/sig/ld.d.ts
+/**
+ * A signature of a JSON-LD document.
+ * @since 1.0.0
+ */
+interface Signature {
+  "@context"?: "https://w3id.org/identity/v1";
+  type: "RsaSignature2017";
+  id?: string;
+  creator: string;
+  created: string;
+  signatureValue: string;
+}
+/**
+ * Attaches a LD signature to the given JSON-LD document.
+ * @param jsonLd The JSON-LD document to attach the signature to.  It is not
+ *               modified.
+ * @param signature The signature to attach.
+ * @returns The JSON-LD document with the attached signature.
+ * @throws {TypeError} If the input document is not a valid JSON-LD document.
+ * @since 1.0.0
+ */
+declare function attachSignature(jsonLd: unknown, signature: Signature): {
+  signature: Signature;
+};
+/**
+ * Options for creating Linked Data Signatures.
+ * @since 1.0.0
+ */
+interface CreateSignatureOptions {
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The time when the signature was created.  If not specified, the current
+   * time will be used.
+   */
+  created?: Temporal.Instant;
+}
+/**
+ * Creates a LD signature for the given JSON-LD document.
+ * @param jsonLd The JSON-LD document to sign.
+ * @param privateKey The private key to sign the document.
+ * @param keyId The ID of the public key that corresponds to the private key.
+ * @param options Additional options for creating the signature.
+ *                See also {@link CreateSignatureOptions}.
+ * @return The created signature.
+ * @throws {TypeError} If the private key is invalid or unsupported.
+ * @since 1.0.0
+ */
+declare function createSignature(jsonLd: unknown, privateKey: CryptoKey, keyId: URL, {
+  contextLoader,
+  created
+}?: CreateSignatureOptions): Promise<Signature>;
+/**
+ * Options for signing JSON-LD documents.
+ * @since 1.0.0
+ */
+interface SignJsonLdOptions extends CreateSignatureOptions {
+  /**
+   * The OpenTelemetry tracer provider for tracing the signing process.
+   * If omitted, the global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Signs the given JSON-LD document with the private key and returns the signed
+ * JSON-LD document.
+ * @param jsonLd The JSON-LD document to sign.
+ * @param privateKey The private key to sign the document.
+ * @param keyId The key ID to use in the signature.  It will be used by the
+ *              verifier to fetch the corresponding public key.
+ * @param options Additional options for signing the document.
+ *                See also {@link SignJsonLdOptions}.
+ * @returns The signed JSON-LD document.
+ * @throws {TypeError} If the private key is invalid or unsupported.
+ * @since 1.0.0
+ */
+declare function signJsonLd(jsonLd: unknown, privateKey: CryptoKey, keyId: URL, options: SignJsonLdOptions): Promise<{
+  signature: Signature;
+}>;
+/**
+ * Detaches Linked Data Signatures from the given JSON-LD document.
+ * @param jsonLd The JSON-LD document to modify.
+ * @returns The modified JSON-LD document.  If the input document does not
+ *          contain a signature, the original document is returned.
+ * @since 1.0.0
+ */
+declare function detachSignature(jsonLd: unknown): unknown;
+/**
+ * Options for verifying Linked Data Signatures.
+ * @since 1.0.0
+ */
+interface VerifySignatureOptions {
+  /**
+   * The document loader to use for fetching the public key.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader to use for JSON-LD context retrieval.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The key cache to use for caching public keys.
+   */
+  keyCache?: KeyCache;
+  /**
+   * The OpenTelemetry tracer provider for tracing the verification process.
+   * If omitted, the global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Verifies Linked Data Signatures of the given JSON-LD document.
+ * @param jsonLd The JSON-LD document to verify.
+ * @param options Options for verifying the signature.
+ * @returns The public key that signed the document or `null` if the signature
+ *          is invalid or the key is not found.
+ * @since 1.0.0
+ */
+declare function verifySignature(jsonLd: unknown, options?: VerifySignatureOptions): Promise<CryptographicKey | null>;
+/**
+ * Options for verifying JSON-LD documents.
+ */
+interface VerifyJsonLdOptions extends VerifySignatureOptions {}
+/**
+ * Verify the authenticity of the given JSON-LD document using Linked Data
+ * Signatures.  If the document is signed, this function verifies the signature
+ * and checks if the document is attributed to the owner of the public key.
+ * If the document is not signed, this function returns `false`.
+ * @param jsonLd The JSON-LD document to verify.
+ * @param options Options for verifying the document.
+ * @returns `true` if the document is authentic; `false` otherwise.
+ */
+declare function verifyJsonLd(jsonLd: unknown, options?: VerifyJsonLdOptions): Promise<boolean>;
+//#endregion
+//#region src/sig/proof.d.ts
+/**
+ * Options for {@link createProof}.
+ * @since 0.10.0
+ */
+interface CreateProofOptions {
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The JSON-LD context to use for serializing the object to sign.
+   */
+  context?: string | Record<string, string> | (string | Record<string, string>)[];
+  /**
+   * The time when the proof was created.  If not specified, the current time
+   * will be used.
+   */
+  created?: Temporal.Instant;
+}
+/**
+ * Creates a proof for the given object.
+ * @param object The object to create a proof for.
+ * @param privateKey The private key to sign the proof with.
+ * @param keyId The key ID to use in the proof. It will be used by the verifier.
+ * @param options Additional options.  See also {@link CreateProofOptions}.
+ * @returns The created proof.
+ * @throws {TypeError} If the private key is invalid or unsupported.
+ * @since 0.10.0
+ */
+declare function createProof(object: Object$1, privateKey: CryptoKey, keyId: URL, {
+  contextLoader,
+  context,
+  created
+}?: CreateProofOptions): Promise<DataIntegrityProof>;
+/**
+ * Options for {@link signObject}.
+ * @since 0.10.0
+ */
+interface SignObjectOptions extends CreateProofOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Signs the given object with the private key and returns the signed object.
+ * @param object The object to create a proof for.
+ * @param privateKey The private key to sign the proof with.
+ * @param keyId The key ID to use in the proof. It will be used by the verifier.
+ * @param options Additional options.  See also {@link SignObjectOptions}.
+ * @returns The signed object.
+ * @throws {TypeError} If the private key is invalid or unsupported.
+ * @since 0.10.0
+ */
+declare function signObject<T extends Object$1>(object: T, privateKey: CryptoKey, keyId: URL, options?: SignObjectOptions): Promise<T>;
+/**
+ * Options for {@link verifyProof}.
+ * @since 0.10.0
+ */
+interface VerifyProofOptions {
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The key cache to use for caching public keys.
+   * @since 0.12.0
+   */
+  keyCache?: KeyCache;
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Verifies the given proof for the object.
+ * @param jsonLd The JSON-LD object to verify the proof for.  If it contains
+ *               any proofs, they will be ignored.
+ * @param proof The proof to verify.
+ * @param options Additional options.  See also {@link VerifyProofOptions}.
+ * @returns The public key that was used to sign the proof, or `null` if the
+ *          proof is invalid.
+ * @since 0.10.0
+ */
+declare function verifyProof(jsonLd: unknown, proof: DataIntegrityProof, options?: VerifyProofOptions): Promise<Multikey | null>;
+/**
+ * Options for {@link verifyObject}.
+ * @since 0.10.0
+ */
+interface VerifyObjectOptions extends VerifyProofOptions {}
+/**
+ * Verifies the given object.  It will verify all the proofs in the object,
+ * and succeed only if all the proofs are valid and all attributions and
+ * actors are authenticated by the proofs.
+ * @template T The type of the object to verify.
+ * @param cls The class of the object to verify.  It must be a subclass of
+ *            the {@link Object}.
+ * @param jsonLd The JSON-LD object to verify.  It's assumed that the object
+ *               is a compacted JSON-LD representation of a `T` with `@context`.
+ * @param options Additional options.  See also {@link VerifyObjectOptions}.
+ * @returns The object if it's verified, or `null` if it's not.
+ * @throws {TypeError} If the object is invalid or unsupported.
+ * @since 0.10.0
+ */
+declare function verifyObject<T extends Object$1>(cls: (new (...args: any[]) => T) & {
+  fromJsonLd(jsonLd: unknown, options: VerifyObjectOptions): Promise<T>;
+}, jsonLd: unknown, options?: VerifyObjectOptions): Promise<T | null>;
+//#endregion
+export { CreateProofOptions, CreateSignatureOptions, SignJsonLdOptions, SignObjectOptions, VerifyJsonLdOptions, VerifyObjectOptions, VerifyProofOptions, VerifySignatureOptions, attachSignature, createProof, createSignature, detachSignature, signJsonLd, signObject, verifyJsonLd, verifyObject, verifyProof, verifySignature };

package/dist/{mod-Cxt4Kpf6.d.ts → mod-DlU8ISoa.d.ts}

@@ -1,7 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { URLPattern } from "urlpattern-polyfill";
 import { DocumentLoader, GetUserAgentOptions } from "./docloader-CxWcuWqQ.js";
-import { Collection, Link, Object as Object$1 } from "./vocab-SOE1ifCr.js";
+import { Collection, Link, Object as Object$1 } from "./vocab-BI0Ak5lL.js";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/vocab/lookup.d.ts
@@ -20,6 +20,24 @@ interface LookupObjectOptions {
    * @since 0.8.0
    */
   contextLoader?: DocumentLoader;
+  /**
+   * Whether to allow fetching an object with an `@id` having a different
+   * origin than the object's URL.  This is not recommended, as it may
+   * lead to security issues.  Only use this option if you know what you
+   * are doing.
+   *
+   * How to handle the case when an object's `@id` has a different origin
+   * than the object's URL:
+   *
+   *  -  `"ignore"` (default): Do not return the object, and log a warning.
+   *  -  `"throw"`: Throw an error.
+   *  -  `"trust"`: Bypass the check and return the object anyway.  This
+   *     is not recommended, as it may lead to security issues.  Only use
+   *     this option if you know what you are doing.
+   *
+   * @since 1.9.0
+   */
+  crossOrigin?: "ignore" | "throw" | "trust";
   /**
    * The options for making `User-Agent` header.
    * If a string is given, it is used as the `User-Agent` header value.

package/dist/mod-FZd39qVq.d.cts

@@ -0,0 +1 @@
+export { };