@fedify/vocab-runtime 2.4.0-pr.934.40 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/deno.json +4 -2
  2. package/dist/{tests/docloader-Xi61Le8w.mjs → contexts-BK1CqBR5.cjs} +164 -269
  3. package/dist/{tests/docloader-BFedvemb.cjs → contexts-DPuJ4UYL.js} +160 -288
  4. package/dist/{docloader-DnUMWHaJ.d.cts → docloader-CYwqh5Df.d.cts} +68 -2
  5. package/dist/{docloader-xRGn1azD.d.ts → docloader-CYwqh5Df.d.ts} +68 -2
  6. package/dist/internal/jsonld-cache.cjs +70 -1
  7. package/dist/internal/jsonld-cache.d.cts +35 -2
  8. package/dist/internal/jsonld-cache.d.ts +35 -2
  9. package/dist/internal/jsonld-cache.js +67 -2
  10. package/dist/internal/portable-dereference.cjs +721 -0
  11. package/dist/internal/portable-dereference.d.cts +349 -0
  12. package/dist/internal/portable-dereference.d.ts +349 -0
  13. package/dist/internal/portable-dereference.js +702 -0
  14. package/dist/internal/signed-representation.cjs +378 -0
  15. package/dist/internal/signed-representation.d.cts +144 -0
  16. package/dist/internal/signed-representation.d.ts +144 -0
  17. package/dist/internal/signed-representation.js +371 -0
  18. package/dist/jsonld.cjs +2 -2
  19. package/dist/mod.cjs +715 -4523
  20. package/dist/mod.d.cts +406 -6
  21. package/dist/mod.d.ts +406 -7
  22. package/dist/mod.js +694 -4518
  23. package/dist/portable-DqtfLy_1.d.cts +160 -0
  24. package/dist/portable-DtWsu2yU.d.ts +160 -0
  25. package/dist/tests/body-CYiu9CO-.mjs +130 -0
  26. package/dist/tests/body-CkEwROsn.cjs +153 -0
  27. package/dist/tests/body.test.cjs +89 -0
  28. package/dist/tests/body.test.d.cts +1 -0
  29. package/dist/tests/body.test.d.mts +1 -0
  30. package/dist/tests/body.test.mjs +90 -0
  31. package/dist/tests/contexts-CIKsin4e.mjs +4512 -0
  32. package/dist/tests/contexts-DizzBjz4.cjs +4523 -0
  33. package/dist/tests/decimal.test.cjs +8 -7
  34. package/dist/tests/decimal.test.mjs +8 -6
  35. package/dist/tests/digest-3FeH2Y-Q.cjs +176 -0
  36. package/dist/tests/digest-COC7xDiQ.mjs +141 -0
  37. package/dist/tests/digest.test.cjs +102 -0
  38. package/dist/tests/digest.test.d.cts +1 -0
  39. package/dist/tests/digest.test.d.mts +1 -0
  40. package/dist/tests/digest.test.mjs +103 -0
  41. package/dist/tests/docloader-C3YFl6y4.cjs +396 -0
  42. package/dist/tests/docloader-CvmS4sVq.mjs +373 -0
  43. package/dist/tests/docloader.test.cjs +692 -39
  44. package/dist/tests/docloader.test.mjs +686 -34
  45. package/dist/tests/internal/multicodec.test.cjs +2 -3
  46. package/dist/tests/internal/multicodec.test.mjs +2 -2
  47. package/dist/tests/internal/portable-dereference.test.cjs +172 -0
  48. package/dist/tests/internal/portable-dereference.test.d.cts +1 -0
  49. package/dist/tests/internal/portable-dereference.test.d.mts +1 -0
  50. package/dist/tests/internal/portable-dereference.test.mjs +173 -0
  51. package/dist/tests/jsonld-cache-BPQmOZWD.mjs +342 -0
  52. package/dist/tests/jsonld-cache-C07AyNOY.cjs +397 -0
  53. package/dist/tests/jsonld-cache.test.cjs +101 -298
  54. package/dist/tests/jsonld-cache.test.mjs +94 -289
  55. package/dist/tests/{key-_wXwomh_.cjs → key-C-AYkdJJ.cjs} +11 -4
  56. package/dist/tests/{key-CDGDH_vC.mjs → key-C2Db_TAJ.mjs} +11 -3
  57. package/dist/tests/key.test.cjs +6 -5
  58. package/dist/tests/key.test.mjs +6 -4
  59. package/dist/tests/langstr.test.cjs +4 -4
  60. package/dist/tests/langstr.test.mjs +2 -2
  61. package/dist/tests/link.test.cjs +2 -3
  62. package/dist/tests/link.test.mjs +2 -2
  63. package/dist/tests/multibase/multibase.test.cjs +8 -9
  64. package/dist/tests/multibase/multibase.test.mjs +6 -6
  65. package/dist/tests/{multibase-Bz_UUDtL.cjs → multibase-B5Mea7Ip.cjs} +19 -2
  66. package/dist/tests/{multibase-B4bvakyA.mjs → multibase-BPnF_L4e.mjs} +12 -1
  67. package/dist/tests/portable-dereference-BNXtgg5U.cjs +278 -0
  68. package/dist/tests/portable-dereference-DRE5bz-l.mjs +249 -0
  69. package/dist/tests/portable-media-BLKllU56.cjs +153 -0
  70. package/dist/tests/portable-media-DRSGBORB.mjs +148 -0
  71. package/dist/tests/portable-media.test.cjs +222 -0
  72. package/dist/tests/portable-media.test.d.cts +1 -0
  73. package/dist/tests/portable-media.test.d.mts +1 -0
  74. package/dist/tests/portable-media.test.mjs +223 -0
  75. package/dist/tests/portable-workers.test.cjs +36 -0
  76. package/dist/tests/portable-workers.test.d.cts +2 -0
  77. package/dist/tests/portable-workers.test.d.mts +2 -0
  78. package/dist/tests/portable-workers.test.mjs +35 -0
  79. package/dist/tests/{request-cCPgOxYG.cjs → request-8vPWtV1-.cjs} +10 -4
  80. package/dist/tests/{request-BOS-hNaf.mjs → request-DRaOaTqD.mjs} +8 -2
  81. package/dist/tests/request.test.cjs +7 -4
  82. package/dist/tests/request.test.mjs +5 -2
  83. package/dist/tests/signed-representation.test.cjs +588 -0
  84. package/dist/tests/signed-representation.test.d.cts +1 -0
  85. package/dist/tests/signed-representation.test.d.mts +1 -0
  86. package/dist/tests/signed-representation.test.mjs +589 -0
  87. package/dist/tests/temporal.test.cjs +1 -2
  88. package/dist/tests/temporal.test.mjs +1 -1
  89. package/dist/tests/url-BNakuZ8k.cjs +998 -0
  90. package/dist/tests/url-DMxmp7ZG.mjs +859 -0
  91. package/dist/tests/url.test.cjs +503 -3
  92. package/dist/tests/url.test.mjs +503 -2
  93. package/dist/url-DrGTR8yv.cjs +993 -0
  94. package/dist/url-Dzyp-NsC.js +860 -0
  95. package/package.json +27 -4
  96. package/scripts/test-bun.mjs +17 -0
  97. package/src/body.test.ts +125 -0
  98. package/src/body.ts +152 -0
  99. package/src/contexts/cid-v1.json +114 -0
  100. package/src/contexts/fep-22cd.json +21 -0
  101. package/src/contexts/fep-ef61.json +10 -0
  102. package/src/contexts/miscellany.json +17 -0
  103. package/src/contexts/security-data-integrity-v1.json +0 -4
  104. package/src/contexts.ts +40 -0
  105. package/src/digest.test.ts +220 -0
  106. package/src/digest.ts +229 -0
  107. package/src/docloader.test.ts +918 -27
  108. package/src/docloader.ts +322 -105
  109. package/src/internal/jsonld-cache.ts +97 -1
  110. package/src/internal/portable-dereference.test.ts +254 -0
  111. package/src/internal/portable-dereference.ts +1000 -0
  112. package/src/internal/signed-representation.ts +565 -0
  113. package/src/jsonld-cache.test.ts +89 -0
  114. package/src/key.test.ts +9 -0
  115. package/src/key.ts +11 -1
  116. package/src/mod.ts +30 -0
  117. package/src/multibase/multibase.test.ts +5 -5
  118. package/src/portable-media.test.ts +293 -0
  119. package/src/portable-media.ts +264 -0
  120. package/src/portable-workers.test.ts +81 -0
  121. package/src/portable.ts +180 -0
  122. package/src/preprocessor.ts +7 -0
  123. package/src/request.test.ts +10 -1
  124. package/src/request.ts +9 -1
  125. package/src/signed-representation.test.ts +338 -0
  126. package/src/url.test.ts +844 -1
  127. package/src/url.ts +717 -17
  128. package/tsdown.config.ts +2 -0
  129. package/dist/tests/url-BvjYQdxL.cjs +0 -456
  130. package/dist/tests/url-a2D8NAgh.mjs +0 -378
  131. package/dist/url-Ck3dGEwH.cjs +0 -457
  132. package/dist/url-m1YxGNZ0.js +0 -379
  133. /package/dist/{chunk-M78iaK0I.cjs → rolldown-runtime-B7lfambq.cjs} +0 -0
  134. /package/dist/tests/{langstr-CbAxaeEZ.cjs → langstr-C4Fl80ae.cjs} +0 -0
  135. /package/dist/tests/{langstr-Di5AvKpB.mjs → langstr-CQ26J_L7.mjs} +0 -0
  136. /package/dist/tests/{link-NUUWCdnK.mjs → link-Cevmc87v.mjs} +0 -0
  137. /package/dist/tests/{link-FguCydMA.cjs → link-DlKm8bEr.cjs} +0 -0
  138. /package/dist/tests/{multicodec-CxGVGa91.cjs → multicodec-CLRPeW4N.cjs} +0 -0
  139. /package/dist/tests/{multicodec-CyFp54fI.mjs → multicodec-CRIj_05H.mjs} +0 -0
  140. /package/dist/tests/{chunk-C2EiDwsr.cjs → rolldown-runtime-emK7D4bc.cjs} +0 -0
package/dist/mod.d.cts CHANGED
@@ -1,5 +1,6 @@
1
1
  /// <reference lib="esnext.temporal" />
2
- import { a as DocumentLoaderOptions, c as getDocumentLoader, d as FetchError, f as GetUserAgentOptions, h as logRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as getUserAgent, n as DocumentLoader, o as GetDocumentLoaderOptions, p as createActivityPubRequest, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as CreateRequestOptions } from "./docloader-DnUMWHaJ.cjs";
2
+ import { _ as logRequest, a as DocumentLoaderOptions, c as getDocumentLoader, d as withDocumentLoaderTimeout, f as CreateRequestOptions, g as getUserAgent, h as createActivityPubRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as GetUserAgentOptions, n as DocumentLoader, o as GetDocumentLoaderOptions, p as FetchError, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as resolveDocumentLoaderTimeout } from "./docloader-CYwqh5Df.cjs";
3
+ import { i as PortableObjectVerifierOptions, n as PortableObjectVerification, r as PortableObjectVerifier, t as PortableObjectReferrer } from "./portable-DqtfLy_1.cjs";
3
4
  import { TracerProvider } from "@opentelemetry/api";
4
5
 
5
6
  //#region src/contexts.d.ts
@@ -73,9 +74,16 @@ declare function importDidKey(did: string | URL): Promise<CryptoKey>;
73
74
  /**
74
75
  * Exports an Ed25519 public key as a `did:key` DID.
75
76
  *
77
+ * The DID is encoded in base58-btc with the Ed25519 multicodec prefix, e.g.,
78
+ * `did:key:z6Mk...`, as [FEP-ef61] requires for the DIDs of portable
79
+ * objects.
80
+ *
81
+ * [FEP-ef61]: https://w3id.org/fep/ef61
82
+ *
76
83
  * @param key The Ed25519 public key.
77
84
  * @returns The `did:key` DID.
78
- * @throws {TypeError} If the key is invalid or unsupported.
85
+ * @throws {TypeError} If the key is invalid or unsupported, or it is not
86
+ * a public key.
79
87
  * @since 2.4.0
80
88
  */
81
89
  declare function exportDidKey(key: CryptoKey): Promise<string>;
@@ -204,6 +212,87 @@ declare function canParseDecimal(value: string): boolean;
204
212
  */
205
213
  declare function parseDecimal(value: string): Decimal;
206
214
  //#endregion
215
+ //#region src/digest.d.ts
216
+ /**
217
+ * A parsed SHA-256 resource digest.
218
+ *
219
+ * @since 2.4.0
220
+ */
221
+ interface ParsedDigestMultibase {
222
+ /** The multihash algorithm represented by the digest. */
223
+ readonly algorithm: "sha2-256";
224
+ /** The raw 32-byte SHA-256 digest. */
225
+ readonly digest: Uint8Array;
226
+ }
227
+ /**
228
+ * A parsed simple hashlink.
229
+ *
230
+ * @since 2.4.0
231
+ */
232
+ interface ParsedHashlink {
233
+ /** The multibase-encoded multihash carried by the hashlink. */
234
+ readonly digestMultibase: string;
235
+ }
236
+ /**
237
+ * Computes the SHA-256 digest of a byte sequence and encodes it as a
238
+ * base58-btc multibase multihash suitable for FEP-ef61's
239
+ * `digestMultibase` property.
240
+ *
241
+ * @param bytes The bytes to digest.
242
+ * @returns The base58-btc multibase-encoded SHA-256 multihash.
243
+ * @since 2.4.0
244
+ */
245
+ declare function computeDigestMultibase(bytes: Uint8Array): Promise<string>;
246
+ /**
247
+ * Parses and validates a SHA-256 `digestMultibase` value.
248
+ *
249
+ * @param value The multibase-encoded multihash to parse.
250
+ * @returns The digest algorithm and raw digest bytes.
251
+ * @throws {TypeError} If the value is malformed or uses an unsupported hash
252
+ * algorithm.
253
+ * @since 2.4.0
254
+ */
255
+ declare function parseDigestMultibase(value: string): ParsedDigestMultibase;
256
+ /**
257
+ * Parses a metadata-free `hl:` hashlink and validates its resource digest.
258
+ *
259
+ * @param value The simple hashlink to parse.
260
+ * @returns The `digestMultibase` value carried by the hashlink.
261
+ * @throws {TypeError} If the hashlink is malformed, contains metadata, or
262
+ * carries an invalid or unsupported digest.
263
+ * @since 2.4.0
264
+ */
265
+ declare function parseHashlink(value: string | URL): ParsedHashlink;
266
+ /**
267
+ * Creates a metadata-free `hl:` hashlink from a `digestMultibase` value.
268
+ *
269
+ * @param digestMultibase The SHA-256 multibase multihash to embed.
270
+ * @returns The simple hashlink.
271
+ * @throws {TypeError} If the digest is malformed or unsupported.
272
+ * @since 2.4.0
273
+ */
274
+ declare function createHashlink(digestMultibase: string): string;
275
+ /**
276
+ * Verifies that bytes match a SHA-256 `digestMultibase` value.
277
+ *
278
+ * @param bytes The bytes to verify.
279
+ * @param digestMultibase The expected digest.
280
+ * @returns Whether the bytes match the digest.
281
+ * @throws {TypeError} If the digest is malformed or unsupported.
282
+ * @since 2.4.0
283
+ */
284
+ declare function verifyDigestMultibase(bytes: Uint8Array, digestMultibase: string): Promise<boolean>;
285
+ /**
286
+ * Verifies that bytes match the resource digest in a simple hashlink.
287
+ *
288
+ * @param bytes The bytes to verify.
289
+ * @param hashlink The simple hashlink containing the expected digest.
290
+ * @returns Whether the bytes match the hashlink digest.
291
+ * @throws {TypeError} If the hashlink or digest is malformed or unsupported.
292
+ * @since 2.4.0
293
+ */
294
+ declare function verifyHashlink(bytes: Uint8Array, hashlink: string | URL): Promise<boolean>;
295
+ //#endregion
207
296
  //#region src/langstr.d.ts
208
297
  /**
209
298
  * A language-tagged string which corresponds to the `rdf:langString` type.
@@ -223,6 +312,50 @@ declare class LanguageString extends String {
223
312
  constructor(value: string, language: Intl.Locale | string);
224
313
  }
225
314
  //#endregion
315
+ //#region src/portable-media.d.ts
316
+ /** A link or document with an external resource and its integrity digest. */
317
+ interface PortableMedia {
318
+ readonly href?: URL | null;
319
+ readonly url?: URL | {
320
+ readonly href: URL | null;
321
+ readonly digestMultibase?: string | null;
322
+ } | null;
323
+ readonly digestMultibase?: string | null;
324
+ }
325
+ /** Options for {@link fetchPortableMedia}. */
326
+ interface FetchPortableMediaOptions {
327
+ /** Ordered FEP-ef61 gateway origins used for `hl:` resources. */
328
+ readonly gateways?: Iterable<string | URL>;
329
+ /** Expected digest when the first argument is a URL or string. */
330
+ readonly digestMultibase?: string;
331
+ /** Maximum decoded response size in bytes. Defaults to 16 MiB. */
332
+ readonly maxBytes?: number;
333
+ /** Whether private network addresses may be fetched. Defaults to `false`. */
334
+ readonly allowPrivateAddress?: boolean;
335
+ /** The HTTP `User-Agent` value or its components. */
336
+ readonly userAgent?: string | GetUserAgentOptions;
337
+ /** Cancels the entire retrieval and all gateway attempts. */
338
+ readonly signal?: AbortSignal;
339
+ /** Overall timeout in milliseconds. Defaults to 10 seconds; `null` disables it. */
340
+ readonly timeout?: number | null;
341
+ /** Timeout per gateway in milliseconds. Defaults to 3 seconds. */
342
+ readonly gatewayTimeout?: number | null;
343
+ }
344
+ /**
345
+ * Fetches a portable object's external media and returns it only after its
346
+ * SHA-256 `digestMultibase` has been verified. `hl:` resources are tried at
347
+ * the supplied gateways in order. The result contains verified body bytes;
348
+ * its `Content-Type` is unverified metadata supplied by the server.
349
+ *
350
+ * @param media A Link, Image, Document, or URL with an external resource.
351
+ * @param options Retrieval, integrity, and network policy options.
352
+ * @returns A response containing only verified bytes.
353
+ * @throws {TypeError} If the media reference or digest is invalid.
354
+ * @throws {Error} If no source supplies a matching bounded resource.
355
+ * @since 2.4.0
356
+ */
357
+ declare function fetchPortableMedia(media: string | URL | PortableMedia, options?: FetchPortableMediaOptions): Promise<Response>;
358
+ //#endregion
226
359
  //#region src/multibase/types.d.ts
227
360
  type BaseCode = "\x00" | "0" | "7" | "9" | "f" | "F" | "v" | "V" | "t" | "T" | "b" | "B" | "c" | "C" | "h" | "k" | "K" | "z" | "Z" | "m" | "M" | "u" | "U";
228
361
  /**
@@ -295,6 +428,12 @@ interface PropertyPreprocessorContext {
295
428
  contextLoader?: DocumentLoader;
296
429
  /** OpenTelemetry tracer provider for instrumentation. */
297
430
  tracerProvider?: TracerProvider;
431
+ /**
432
+ * The default FEP-ef61 portable object verifier that objects returned by
433
+ * the preprocessor should use for their property accessors.
434
+ * @since 2.4.0
435
+ */
436
+ verifyPortableObject?: PortableObjectVerifier;
298
437
  /** Base URL for resolving relative references. */
299
438
  baseUrl?: URL;
300
439
  }
@@ -311,18 +450,66 @@ type PropertyPreprocessor<T = unknown> = (value: Json, context: PropertyPreproce
311
450
  //#endregion
312
451
  //#region src/url.d.ts
313
452
  declare class UrlError extends Error {
314
- constructor(message: string);
453
+ /**
454
+ * The failure category. Defaults to `"disallowed"`.
455
+ * `"dns"` includes lookup errors and results with no usable IP addresses.
456
+ * @since 2.0.29
457
+ */
458
+ readonly reason: "dns" | "disallowed";
459
+ constructor(message: string, options?: {
460
+ cause?: unknown;
461
+ reason?: "dns" | "disallowed";
462
+ });
315
463
  }
316
464
  /**
317
- * Parses a JSON-LD `@id` value as an IRI.
465
+ * Parses a JSON-LD `@id` value as an IRI, including FEP-ef61 portable
466
+ * ActivityPub IRIs. See {@link parseIri} for how IRIs are parsed.
467
+ * @param id The `@id` value.
468
+ * @param base The base IRI to resolve a relative `@id` against.
469
+ * @returns The parsed IRI, or `undefined` if `id` is missing or a blank node
470
+ * identifier.
471
+ * @throws {TypeError} If `id` is not a valid IRI.
472
+ * @since 2.4.0
318
473
  */
319
474
  declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
320
475
  /**
321
476
  * Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
477
+ * Portable URI and FEP-ef61 compatible identifier strings whose path contains
478
+ * a `.` or `..` segment, including percent-encoded spellings, throw a
479
+ * `TypeError`: JavaScript `URL` would otherwise identify a different object.
480
+ * This also applies to compatible identifier strings used as relative bases.
481
+ * A `URL` argument may already have lost such segments before this function
482
+ * receives it.
483
+ *
484
+ * Portable IRIs, e.g., `ap://did:key:z6Mk.../actor`, cannot be represented by
485
+ * JavaScript `URL` as they are, so the returned `URL` keeps the DID authority
486
+ * percent-encoded, e.g., `ap+ef61://did%3Akey%3Az6Mk.../actor`. Use
487
+ * {@link formatIri} to get the canonical string back.
488
+ * @param iri The IRI to parse.
489
+ * @param base The base IRI to resolve a relative IRI against.
490
+ * @returns The parsed IRI.
491
+ * @throws {TypeError} If the IRI is malformed.
492
+ * @since 2.4.0
322
493
  */
323
494
  declare function parseIri(iri: string | URL, base?: string | URL): URL;
324
495
  /**
325
496
  * Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
497
+ * Portable URI and FEP-ef61 compatible identifier strings with dot segments
498
+ * throw a `TypeError` because their paths cannot be represented by JavaScript
499
+ * `URL` without normalization.
500
+ *
501
+ * Portable IRIs are formatted with the `ap+ef61:` scheme and a decoded DID
502
+ * authority, even if they were parsed from `ap:` IRIs. FEP-ef61 currently
503
+ * recommends the `ap:` scheme, so a future major version of Fedify may change
504
+ * the scheme this function produces. Do not compare its results as strings to
505
+ * tell whether two portable IRIs identify the same object; use
506
+ * `arePortableUrisEqual()` instead.
507
+ * @param iri The IRI to format.
508
+ * @returns The formatted IRI. A string that cannot be parsed as a URL at all
509
+ * is returned unchanged.
510
+ * @throws {TypeError} If the IRI is a malformed portable IRI or FEP-ef61
511
+ * compatible identifier, e.g., one with dot segments.
512
+ * @since 2.4.0
326
513
  */
327
514
  declare function formatIri(iri: string | URL): string;
328
515
  /**
@@ -334,6 +521,12 @@ declare function formatIri(iri: string | URL): string;
334
521
  * string, not a `URL` object, because JavaScript `URL` normalizes opaque path
335
522
  * segments before Fedify can compare them.
336
523
  *
524
+ * The `ap+ef61:` scheme of the result is a choice of Fedify's, whereas
525
+ * FEP-ef61 currently canonicalizes portable URIs with the `ap:` scheme.
526
+ * A future major version of Fedify may change the scheme of the result, so
527
+ * do not persist the result as the only copy of an identifier; keep the
528
+ * original URI, and canonicalize it again when comparing.
529
+ *
337
530
  * @param input The raw portable ActivityPub URI string to canonicalize.
338
531
  * @returns The canonical portable ActivityPub URI string.
339
532
  * @throws {TypeError} If the input is not a valid portable ActivityPub IRI.
@@ -371,10 +564,217 @@ declare function getFe34Origin(input: string | URL): string;
371
564
  */
372
565
  declare function haveSameFe34Origin(left: string | URL, right: string | URL): boolean;
373
566
  /**
374
- * Checks whether two IRIs have the same origin.
567
+ * Checks whether two IRIs have the same origin. Unlike comparing
568
+ * `URL.origin`, which is `"null"` for URLs with non-special schemes, this
569
+ * compares FEP-ef61 portable ActivityPub IRIs by their schemes and DIDs, so
570
+ * that `ap:` and `ap+ef61:` IRIs of the same DID with decoded or
571
+ * percent-encoded authorities have the same origin. Other IRIs with
572
+ * a non-special scheme and a host are compared by their schemes and hosts.
573
+ *
574
+ * This is not an FEP-fe34 origin check: an `ap+ef61:` IRI and the `did:key`
575
+ * verification method of the same DID have different origins here. Use
576
+ * {@link haveSameFe34Origin} for that.
577
+ * @param left The first IRI.
578
+ * @param right The second IRI.
579
+ * @returns `true` if the IRIs have the same origin.
580
+ * @since 2.4.0
375
581
  */
376
582
  declare function haveSameIriOrigin(left: URL, right: URL): boolean;
377
583
  /**
584
+ * Checks whether the URL is an FEP-ef61 gateway base URI, i.e., an HTTP(S)
585
+ * URI with no credentials, path, query, or fragment, such as
586
+ * `https://example.com/`. FEP-ef61 requires every item of a portable actor's
587
+ * `gateways` to be such a URI. A URI with an empty query or fragment
588
+ * delimiter, such as `https://example.com/?`, is not a gateway base URI.
589
+ *
590
+ * Note that the `URL` class normalizes `https://example.com` to
591
+ * `https://example.com/`, so both are gateway base URIs.
592
+ * @param url The URL to check.
593
+ * @returns `true` if the URL is an FEP-ef61 gateway base URI.
594
+ * @since 2.4.0
595
+ */
596
+ declare function isGatewayUrl(url: URL): boolean;
597
+ /**
598
+ * Parses and validates an FEP-ef61 gateway base URI, i.e., an HTTP(S) URI with
599
+ * no credentials, path, query, or fragment, such as `https://example.com`.
600
+ * See {@link isGatewayUrl} for the rules.
601
+ * @param url The gateway base URI to parse.
602
+ * @returns The parsed gateway base URI, whose path is `/`.
603
+ * @throws {TypeError} If the URI is malformed, or is not an HTTP(S) base URI
604
+ * with no credentials, path, query, or fragment. In the
605
+ * latter case, the message starts with
606
+ * `Invalid FEP-ef61 gateway:`.
607
+ * @since 2.4.0
608
+ */
609
+ declare function parseGatewayUrl(url: string): URL;
610
+ /**
611
+ * Converts an [FEP-ef61] compatible identifier into a portable ActivityPub
612
+ * URI.
613
+ *
614
+ * A compatible identifier is an HTTP(S) URL under a gateway's fixed
615
+ * `/.well-known/apgateway/` path, such as
616
+ * `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
617
+ * This function removes the gateway part and returns the corresponding
618
+ * portable URI, e.g., `ap+ef61://did:key:z6Mk.../objects/1`, in the same
619
+ * internal `URL` form that {@link parseIri} produces. The path, query, and
620
+ * fragment are preserved, so the result is a portable URI, not a comparison
621
+ * form; pass its `href` to {@link canonicalizePortableUri} or
622
+ * {@link arePortableUrisEqual} to compare it with other portable URIs.
623
+ *
624
+ * The conversion only reveals the *claimed* portable identifier. Anyone can
625
+ * publish a compatible identifier for any DID on their own server, so the
626
+ * gateway that served it is neither the object's origin nor authorized to act
627
+ * for the DID. Callers must still verify the retrieved document's Object
628
+ * Integrity Proof against the DID, as FEP-ef61 requires, and should keep the
629
+ * original URL if they need the gateway as a retrieval hint.
630
+ *
631
+ * Arbitrary gateway paths are not supported.
632
+ *
633
+ * [FEP-ef61]: https://w3id.org/fep/ef61
634
+ *
635
+ * @param input The URL to convert.
636
+ * @returns The portable ActivityPub URI, or `null` if the input is not an
637
+ * HTTP(S) URL whose path starts with `/.well-known/apgateway/did:`.
638
+ * Other gateway routes, such as the gateway discovery endpoint and
639
+ * hashlink media URLs, also yield `null`.
640
+ * @throws {TypeError} If the input looks like a compatible identifier but is
641
+ * malformed, e.g., it has an invalid DID, no object path,
642
+ * invalid percent-encoding, credentials, or location
643
+ * hints (`@gateway` query parameters, or the legacy
644
+ * `gateways` parameter), or its raw string path would
645
+ * change during URL parsing. Already-parsed `URL`
646
+ * arguments cannot reveal segments lost by their parser.
647
+ * @since 2.4.0
648
+ */
649
+ declare function fromCompatibleEf61Id(input: string | URL): URL | null;
650
+ /**
651
+ * Converts a portable ActivityPub URI into an [FEP-ef61] compatible
652
+ * identifier, which is an HTTP(S) URL under the gateway's fixed
653
+ * `/.well-known/apgateway/` path.
654
+ *
655
+ * For example, `ap+ef61://did:key:z6Mk.../objects/1` and
656
+ * `https://server.example` yield
657
+ * `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
658
+ * Both `ap:` and `ap+ef61:` URIs with decoded or percent-encoded DID
659
+ * authorities are accepted. Publishers should use the first gateway in the
660
+ * actor's `gateways` list, as FEP-ef61 requires.
661
+ *
662
+ * The path and fragment are preserved, with characters that are not allowed
663
+ * in HTTP(S) URLs percent-encoded the same way as
664
+ * {@link canonicalizePortableUri} does. FEP-ef61 location hints (`@gateway`
665
+ * query parameters, and the legacy `gateways` parameter) are removed, since
666
+ * compatible identifiers must not have them; other query parameters are kept
667
+ * in order.
668
+ *
669
+ * Arbitrary gateway paths are not supported.
670
+ *
671
+ * [FEP-ef61]: https://w3id.org/fep/ef61
672
+ *
673
+ * @param portableId The `ap:` or `ap+ef61:` URI to convert.
674
+ * @param gateway The gateway's HTTP(S) origin, e.g., `https://server.example`.
675
+ * @returns The compatible identifier.
676
+ * @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
677
+ * URI, if its path has `.` or `..` segments (which
678
+ * HTTP(S) URLs cannot represent without changing the
679
+ * identified object), or if the gateway is
680
+ * not an HTTP(S) origin with no credentials, path, query,
681
+ * or fragment.
682
+ * @since 2.4.0
683
+ */
684
+ declare function toCompatibleEf61Id(portableId: string | URL, gateway: string | URL): URL;
685
+ /**
686
+ * Returns a copy of an [FEP-ef61] portable ActivityPub URI with `@gateway`
687
+ * location hints for the given gateways, which tell consumers where they can
688
+ * retrieve the object. Put hints on *references* to portable actors, e.g.,
689
+ * in `actor`, `attributedTo`, `to`, or `cc`, when constructing an object, as
690
+ * FEP-ef61 recommends:
691
+ *
692
+ * ~~~~ typescript
693
+ * withGatewayHints("ap://did:key:z6Mk.../actor", [
694
+ * "https://server1.example",
695
+ * "https://server2.example",
696
+ * ]);
697
+ * // ap+ef61://did:key:z6Mk.../actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example
698
+ * ~~~~
699
+ *
700
+ * Do not put hints on an object's own `id`. Hints do not change the
701
+ * identity of a portable URI, since FEP-ef61 drops the query when comparing
702
+ * portable URIs, but implementations that do not canonicalize portable URIs
703
+ * would take a hinted ID for another object. Add hints before signing the
704
+ * object, since its Object Integrity Proof covers its references too.
705
+ *
706
+ * The hints that the URI already has, including the legacy `gateways`
707
+ * parameter, are replaced. Each gateway becomes a `@gateway` query
708
+ * parameter whose value is its URI-encoded origin, e.g.,
709
+ * `@gateway=https%3A%2F%2Fserver1.example`, in the given order after the
710
+ * other query parameters. Duplicate gateways are dropped, and an empty list
711
+ * removes the hints as {@link withoutGatewayHints} does. The other query
712
+ * parameters, their order, and the fragment are kept, but percent-encoding
713
+ * is normalized the same way as {@link canonicalizePortableUri} does it.
714
+ *
715
+ * Fedify follows at most five hints when dereferencing a portable URI
716
+ * (three for the key ID of an HTTP Signature), so list the preferred
717
+ * gateways first; there is no limit on the number of hints added here.
718
+ *
719
+ * [FEP-ef61]: https://w3id.org/fep/ef61
720
+ *
721
+ * @param portableId The `ap:` or `ap+ef61:` URI. Pass the raw string rather
722
+ * than a `URL` if its path may have `.` or `..` segments,
723
+ * because the `URL` class resolves them.
724
+ * @param gateways The gateways, e.g., the `gateways` of the actor that the
725
+ * URI refers to. Each has to be an HTTP(S) origin with no
726
+ * credentials, path, query, or fragment.
727
+ * @returns The portable URI with the hints, in the same internal `URL` form
728
+ * as {@link parseIri} returns. Use {@link formatIri} to get its
729
+ * canonical string.
730
+ * @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
731
+ * URI, e.g., it is a compatible identifier, which must
732
+ * not have location hints; if its path has `.` or `..`
733
+ * segments, which the `URL` class cannot represent; or
734
+ * if a gateway is invalid.
735
+ * @since 2.4.0
736
+ */
737
+ declare function withGatewayHints(portableId: string | URL, gateways: Iterable<string | URL>): URL;
738
+ /**
739
+ * Returns a copy of an [FEP-ef61] portable ActivityPub URI without its
740
+ * location hints, i.e., `@gateway` query parameters and the legacy
741
+ * `gateways` parameter. The other query parameters, their order, and the
742
+ * fragment are kept, but percent-encoding is normalized the same way as
743
+ * {@link canonicalizePortableUri} does it.
744
+ *
745
+ * [FEP-ef61]: https://w3id.org/fep/ef61
746
+ *
747
+ * @param portableId The `ap:` or `ap+ef61:` URI. Pass the raw string rather
748
+ * than a `URL` if its path may have `.` or `..` segments,
749
+ * because the `URL` class resolves them.
750
+ * @returns The portable URI without the hints, in the same internal `URL`
751
+ * form as {@link parseIri} returns.
752
+ * @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
753
+ * URI, or if its path has `.` or `..` segments, which
754
+ * the `URL` class cannot represent.
755
+ * @since 2.4.0
756
+ */
757
+ declare function withoutGatewayHints(portableId: string | URL): URL;
758
+ /**
759
+ * Gets the gateways in the `@gateway` location hints of an [FEP-ef61]
760
+ * portable ActivityPub URI, in order. Hints that are not valid gateways,
761
+ * i.e., HTTP(S) origins with no credentials, path, query, or fragment, are
762
+ * skipped, and so are duplicates. The legacy `gateways` parameter is not
763
+ * read.
764
+ *
765
+ * Unlike Fedify's dereferencing, which follows at most five hints, this
766
+ * returns all of them.
767
+ *
768
+ * [FEP-ef61]: https://w3id.org/fep/ef61
769
+ *
770
+ * @param portableId The `ap:` or `ap+ef61:` URI.
771
+ * @returns The gateways, e.g., `https://server1.example/`.
772
+ * @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
773
+ * URI.
774
+ * @since 2.4.0
775
+ */
776
+ declare function getGatewayHints(portableId: string | URL): URL[];
777
+ /**
378
778
  * Validates a URL to prevent SSRF attacks.
379
779
  */
380
780
  declare function validatePublicUrl(url: string): Promise<void>;
@@ -382,4 +782,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
382
782
  declare function isValidPublicIPv6Address(address: string): boolean;
383
783
  declare function expandIPv6Address(address: string): string;
384
784
  //#endregion
385
- export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, createActivityPubRequest, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl };
785
+ export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getGatewayHints, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout, withGatewayHints, withoutGatewayHints };