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

package/dist/internal/portable-dereference.d.ts

@@ -0,0 +1,349 @@
+/// <reference lib="esnext.temporal" />
+import { n as DocumentLoader, s as RemoteDocument } from "../docloader-CYwqh5Df.js";
+import { r as PortableObjectVerifier } from "../portable-DtWsu2yU.js";
+import { Span, TracerProvider } from "@opentelemetry/api";
+
+//#region src/internal/portable-dereference.d.ts
+/**
+* A reference from a vocabulary object's property, which generated
+* accessors pass to {@link dereferencePortableIri}.
+*
+* @internal
+*/
+interface PortableReferrerLink {
+  readonly object: object;
+  readonly property: string;
+}
+/**
+* Checks whether a vocabulary object is part of a chain of portable objects,
+* i.e., whether it has a portable ID, has an FEP-ef61 compatible identifier
+* as its ID (even a malformed one, so that it fails closed), or was obtained
+* from a portable object.  Accessors of such objects dereference references
+* as portable objects.
+*
+* Being part of a chain does not mean that the object itself is verified:
+* an object parsed from arbitrary JSON-LD is in a chain just because of its
+* ID.  Only {@link dereferencePortableIri} records that an object was
+* accepted by a verifier.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isInPortableChain(object: object): boolean;
+/**
+* Checks whether a vocabulary object was accepted without an integrity
+* proof, e.g., as an unsecured portable collection served by a trusted
+* gateway.  Objects embedded in such an object must not be trusted because
+* of their origin.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isUnsecuredPortableObject(object: object): boolean;
+/**
+* Checks whether a URL is an FEP-ef61 compatible identifier, i.e., an HTTP(S)
+* URL under a gateway's `/.well-known/apgateway/` path that stands for
+* a portable object.  Malformed compatible identifiers count as compatible
+* identifiers too.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isCompatibleEf61Iri(url: URL | string): boolean;
+/**
+* Records that a vocabulary object returned by a property accessor was
+* obtained through the given property of a portable object, so that later
+* dereferences from it can tell where it came from.  Nothing is recorded if
+* the parent is not in a portable chain, or if the child already has its
+* provenance.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function recordPortableReferrer(parent: object, child: unknown, property: string): void;
+/**
+* Copies the provenance of a vocabulary object to its clone.  The clone
+* keeps where the original came from and the restriction on unsecured
+* objects, but not a positive verification status nor a collection context,
+* since the clone may have different property values.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function copyPortableProvenance(from: object, to: object): void;
+/**
+* Recognizes an FEP-ef61 compatible identifier to dereference as a portable
+* object.
+*
+* @returns `undefined` if the URL is not a compatible identifier; `null` if
+*          it is a malformed compatible identifier; otherwise, the portable
+*          ID it stands for and the gateway it names.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function parseCompatibleEf61Reference(url: URL | string): {
+  readonly id: URL;
+  readonly gateway: URL;
+} | null | undefined;
+/**
+* Checks whether a property accessor call on a vocabulary object applies the
+* FEP-ef61 portable object policy, i.e., whether the `verifyPortableObject`
+* option is given or the object is part of a chain of portable objects.
+* In this mode, compatible identifiers are dereferenced as portable objects,
+* and fetched documents that turn out to stand for portable objects are
+* verified as such.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPortableMode(object: object, options: {
+  readonly verifyPortableObject?: PortableObjectVerifier;
+}): boolean;
+/**
+* Checks whether an object embedded in a property of a vocabulary object has
+* to be dereferenced by its `@id` and verified as a portable object rather
+* than trusted as embedded, even with `crossOrigin: "trust"`.  This is the
+* case in {@link isPortableMode | portable mode} if its `@id` is an FEP-ef61
+* compatible identifier, or a portable IRI whose DID differs from the
+* owner's portable ID.
+*
+* @param parent The object whose property embeds the object.
+* @param ownerId The ID of the object that vouches for embedded objects, or
+*                `null` if embedded objects are not trusted by their owner.
+* @param id The `@id` of the embedded object.
+* @param options The options of the accessor.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function mustDereferencePortableObject(parent: object, ownerId: URL | null, id: URL, options: {
+  readonly verifyPortableObject?: PortableObjectVerifier;
+}): boolean;
+/**
+* The portable object that a document fetched as an ordinary HTTP(S)
+* document claims to be.
+*
+* @internal
+*/
+interface PortableResponseClaim {
+  /** The portable ID that the document has to have. */
+  readonly id: URL;
+  /**
+  * The gateways inferred from the document's URL or `@id`, which are
+  * reported to the verifier as gateway hints.
+  */
+  readonly inferredGateways: readonly URL[];
+}
+/**
+* Finds out whether a document fetched as an ordinary HTTP(S) document
+* claims to be a portable object: its final URL is a portable IRI or an
+* FEP-ef61 compatible identifier, or else its `@id` is.  The final URL takes
+* precedence, so a document whose `@id` claims another object fails the
+* identity check against the final URL.
+*
+* @param documentUrl The final URL of the document.
+* @param objectId The `@id` of the parsed document.
+* @returns `undefined` if the document does not claim to be a portable
+*          object; `null` if the claim is malformed; otherwise, the claim.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function getPortableResponseClaim(documentUrl: string, objectId: URL | null): PortableResponseClaim | null | undefined;
+/**
+* Records that an object fetched as an ordinary HTTP(S) object stands for
+* a portable object if its reference, its final URL, or its `@id` is
+* a portable IRI or an FEP-ef61 compatible identifier.  Accessors do not
+* cache such objects in their parents, so that a later call with the
+* `verifyPortableObject` option dereferences and verifies them.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function markUnverifiedPortableClaim(object: object, reference: URL, documentUrl: string): void;
+/**
+* Checks whether an object was fetched as an ordinary HTTP(S) object although
+* it stands for a portable object.  See {@link markUnverifiedPortableClaim}.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isUnverifiedPortableClaim(object: object): boolean;
+/**
+* Rejects a malformed FEP-ef61 compatible identifier found in a reference,
+* the final URL of a fetched document, or its `@id`, when it would be
+* dereferenced as a portable object.  It is rejected without a request (or
+* without returning the fetched document), since it cannot be verified as
+* a portable object, and fetching it as an ordinary HTTP(S) object would
+* skip the portable object policy.
+*
+* @param url The rejected URL, for the log message.
+* @param options The options of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"` and `suppressError` is not
+*                 set.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function rejectMalformedCompatibleReference(url: string, options: {
+  readonly crossOrigin?: "ignore" | "throw" | "trust";
+  readonly suppressError?: boolean;
+}): null;
+/**
+* Logs that an embedded object without `@id` in an object accepted without
+* an integrity proof is dropped, because it cannot be dereferenced and
+* verified on its own.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function warnUnverifiableEmbeddedObject(parent: object, property: string): void;
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPortableIri(url: URL): boolean;
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+declare function getPortableGatewayCandidates(url: URL, gateways?: readonly (string | URL)[]): URL[];
+/**
+* Gets the gateways through which a portable reference without location hints
+* can be dereferenced, from the portable actor that the reference belongs to.
+*
+* The references in a portable actor's own document, such as its `outbox`,
+* usually have no `@gateway` hints, as they are not needed there, since
+* the actor's `gateways` already tells where to retrieve them.  So this walks
+* from the object whose property is being dereferenced up through the objects
+* it was obtained from, e.g., from a collection page to the collection and
+* then to the actor, and returns the `gateways` of the first object that has
+* any, but only if that object has the same DID as the reference.  The
+* gateways only tell where to look; whatever they serve is still verified.
+*
+* @param object The object whose property is being dereferenced.
+* @param url The portable IRI to dereference.
+* @returns Up to {@link MAX_GATEWAY_HINTS} valid gateways, or `undefined` if
+*          the IRI has valid `@gateway` hints or no such object is found.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function getReferrerGateways(object: object, url: URL): URL[] | undefined;
+/**
+* Creates a context loader that returns the same context documents for the
+* whole dereference operation, so that the identity check, the proof
+* verifier, and the parser interpret the fetched document identically even
+* if the underlying loader is nondeterministic.  Failed loads are not
+* remembered, so a transient failure does not affect the next gateway.
+*
+* The parsed object keeps the loader for its own later dereferences, so
+* `release()` turns it into a plain pass-through to the underlying loader
+* once the operation is over.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function createSnapshotContextLoader(contextLoader: DocumentLoader, suppressError?: boolean): {
+  loader: DocumentLoader;
+  release: () => void;
+};
+/**
+* Options for {@link dereferencePortableIri}.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface DereferencePortableIriOptions<T> {
+  documentLoader: DocumentLoader;
+  contextLoader: DocumentLoader;
+  tracerProvider: TracerProvider;
+  gateways?: readonly (string | URL)[];
+  /**
+  * The gateways inferred from where the reference came from, e.g., the
+  * gateway of a compatible identifier.  When given, they replace the
+  * `@gateway` location hints of the IRI, are asked before the explicit
+  * `gateways`, and are reported to the verifier as gateway hints unless
+  * `gateways` is given.
+  */
+  inferredGateways?: readonly URL[];
+  /**
+  * An already fetched document to validate instead of fetching the object
+  * from gateways.  It is validated the same way as a gateway's response,
+  * and nothing else is tried if it is rejected.
+  */
+  response?: RemoteDocument;
+  verifyPortableObject?: PortableObjectVerifier;
+  referrer?: PortableReferrerLink;
+  suppressError?: boolean;
+  crossOrigin?: "ignore" | "throw" | "trust";
+  /**
+  * The signal for cancelling the dereference.  It is passed to the document
+  * loader for requests to gateways, and checked between attempts.  Requests
+  * for JSON-LD contexts and verification methods may not be cancelled.
+  */
+  signal?: AbortSignal;
+  parse: (document: unknown, options: {
+    contextLoader: DocumentLoader;
+    baseUrl: URL;
+  }) => Promise<T>;
+  span?: Span;
+}
+/**
+* The error thrown by {@link dereferencePortableIri} under
+* `crossOrigin: "throw"` when gateways returned objects but none of them
+* satisfied the identity and proof checks.
+*
+* @internal Not part of the public API contract.
+*/
+declare class PortableObjectRejectedError extends Error {
+  constructor(message: string);
+}
+/**
+* Dereferences an FEP-ef61 portable IRI through its gateways.
+*
+* Gateways are tried one by one until one of them returns a single-node
+* document whose `@id`, if any, canonically matches the requested IRI and
+* which passes `verifyPortableObject`.  When there is no gateway to try, the
+* document loader is asked for the portable IRI itself, and its result is
+* validated the same way.  If the `response` option is given, only that
+* document is validated, and nothing is fetched.
+*
+* @returns The parsed object, or `null` if no valid object was retrieved and
+*          `suppressError` is set or the failure was a rejected object
+*          (unless `crossOrigin` is `"throw"`).
+* @throws {TypeError} If `gateways` has an invalid entry (always), if no
+*                     verifier is given, or if the IRI cannot be turned into
+*                     a gateway URL (unless `suppressError` is set).
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function dereferencePortableIri<T extends {
+  id: URL | null;
+}>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
+//#endregion
+export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };