@interop/wallet-request 0.1.0

package/dist/processRequest.d.ts

@@ -0,0 +1,45 @@
+import type { IVerifiableCredential, IVPRDetails, PresentationSigner, RequestProcessors, WalletResponse } from './types.js';
+/**
+ * Domain-binding check (VCALM §3.4.3 advisement): a DID-Auth `domain` MUST match
+ * the channel the request arrived on, otherwise a dishonest verifier could relay
+ * the challenge from another origin and replay the response.
+ *
+ * @param options {object}
+ * @param options.domain {string} - The `domain` from the request.
+ * @param [options.origin] {string} - The channel origin (for CHAPI,
+ *   `event.credentialRequestOrigin`).
+ * @returns {boolean}
+ */
+export declare function domainMatchesOrigin({ domain, origin }: {
+    domain: string;
+    origin?: string;
+}): boolean;
+/**
+ * Processes a Verifiable Presentation Request and composes the wallet's
+ * response. Assumes the user has already consented and (for VC sharing) picked
+ * which credentials to send.
+ *
+ * @param options {object}
+ * @param options.request {IVPRDetails} - The VPR body.
+ * @param options.presentationSigner {PresentationSigner} - Authentication signer
+ *   and holder DID.
+ * @param [options.selectedVCs] {IVerifiableCredential[]} - VCs the user chose to
+ *   share (empty for a DID-Auth-only or zcap-only response).
+ * @param [options.credentialRequestOrigin] {string} - Channel origin, used for
+ *   the domain-binding check and required by the App Connect branch.
+ * @param [options.processors] {RequestProcessors} - App-side capability /
+ *   App Connect processors.
+ * @param [options.cryptosuite] {string} - Cryptosuite override; when absent it
+ *   is negotiated from the request's `acceptedCryptosuites`.
+ * @returns {Promise<WalletResponse>} The response VP (and any granted zcaps), or
+ *   `{}` when there is nothing to send.
+ */
+export declare function processRequest({ request, presentationSigner, selectedVCs, credentialRequestOrigin, processors, cryptosuite }: {
+    request: IVPRDetails;
+    presentationSigner: PresentationSigner;
+    selectedVCs?: IVerifiableCredential[];
+    credentialRequestOrigin?: string;
+    processors?: RequestProcessors;
+    cryptosuite?: string;
+}): Promise<WalletResponse>;
+//# sourceMappingURL=processRequest.d.ts.map

package/dist/processRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processRequest.d.ts","sourceRoot":"","sources":["../src/processRequest.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,qBAAqB,EACrB,WAAW,EAEX,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAA;AAkBnB;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,MAAM,EACP,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAOV;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,EACnC,OAAO,EACP,kBAAkB,EAClB,WAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,WAAW,CAAA;IACpB,kBAAkB,EAAE,kBAAkB,CAAA;IACtC,WAAW,CAAC,EAAE,qBAAqB,EAAE,CAAA;IACrC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+E1B"}

package/dist/processRequest.js

@@ -0,0 +1,146 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Framework-agnostic request processing: turns a classified VPR body plus the
+ * user's VC selection into a {@link WalletResponse} (a possibly-signed VP, plus
+ * any delegated zcaps). The response channel (CHAPI `respondWith`, an
+ * exchange-URL POST) stays with the caller -- this function only returns data,
+ * and assumes the user has already consented and picked which credentials to
+ * send.
+ *
+ * Ported from Freewallet's `src/lib/walletRequest/processRequest.ts` (the pure
+ * shape). The two app-specific side effects -- capability delegation and the App
+ * Connect branch -- are injected as {@link RequestProcessors} rather than
+ * imported, so this layer carries no session / grant-resolution machinery. The
+ * signer and holder DID are injected as a {@link PresentationSigner}.
+ */
+import { log } from './log.js';
+import { appConnectRequestOf, classifyRequest, queriesOf } from './classify.js';
+import { composeVp } from './composeVp.js';
+import { negotiateCryptosuite } from './presentationSuite.js';
+import { hasAppConnectQuery } from './queryPredicates.js';
+/**
+ * Extracts the host (`host:port`) from a value that may be a full URL or a bare
+ * host / host:port. Returns undefined if it cannot be parsed.
+ */
+function hostOf(value) {
+    try {
+        const url = value.includes('://')
+            ? new URL(value)
+            : new URL(`https://${value}`);
+        return url.host;
+    }
+    catch (err) {
+        log.warn('Could not parse host', { value, err });
+        return undefined;
+    }
+}
+/**
+ * Domain-binding check (VCALM §3.4.3 advisement): a DID-Auth `domain` MUST match
+ * the channel the request arrived on, otherwise a dishonest verifier could relay
+ * the challenge from another origin and replay the response.
+ *
+ * @param options {object}
+ * @param options.domain {string} - The `domain` from the request.
+ * @param [options.origin] {string} - The channel origin (for CHAPI,
+ *   `event.credentialRequestOrigin`).
+ * @returns {boolean}
+ */
+export function domainMatchesOrigin({ domain, origin }) {
+    if (!origin) {
+        return false;
+    }
+    const originHost = hostOf(origin);
+    const domainHost = hostOf(domain);
+    return !!originHost && originHost === domainHost;
+}
+/**
+ * Processes a Verifiable Presentation Request and composes the wallet's
+ * response. Assumes the user has already consented and (for VC sharing) picked
+ * which credentials to send.
+ *
+ * @param options {object}
+ * @param options.request {IVPRDetails} - The VPR body.
+ * @param options.presentationSigner {PresentationSigner} - Authentication signer
+ *   and holder DID.
+ * @param [options.selectedVCs] {IVerifiableCredential[]} - VCs the user chose to
+ *   share (empty for a DID-Auth-only or zcap-only response).
+ * @param [options.credentialRequestOrigin] {string} - Channel origin, used for
+ *   the domain-binding check and required by the App Connect branch.
+ * @param [options.processors] {RequestProcessors} - App-side capability /
+ *   App Connect processors.
+ * @param [options.cryptosuite] {string} - Cryptosuite override; when absent it
+ *   is negotiated from the request's `acceptedCryptosuites`.
+ * @returns {Promise<WalletResponse>} The response VP (and any granted zcaps), or
+ *   `{}` when there is nothing to send.
+ */
+export async function processRequest({ request, presentationSigner, selectedVCs = [], credentialRequestOrigin, processors, cryptosuite }) {
+    const { didAuth, zcapRequests } = classifyRequest(request);
+    const queries = queriesOf(request);
+    const { challenge, domain } = request;
+    // Honor any cryptosuite the verifier asks for (VCALM `acceptedCryptosuites`),
+    // unless the caller pinned one.
+    const negotiatedCryptosuite = cryptosuite ?? negotiateCryptosuite(queries);
+    // Security: never sign an authentication proof bound to a domain the request
+    // did not actually arrive from. Enforced whenever a `domain` is present,
+    // including a zcap-only request whose (unsigned) VP still names an origin.
+    if (domain &&
+        !domainMatchesOrigin({ domain, origin: credentialRequestOrigin })) {
+        throw new Error(`DID Auth domain "${domain}" does not match request origin ` +
+            `"${credentialRequestOrigin}".`);
+    }
+    // An App Connect request takes its own single-round branch, handled by the
+    // injected processor. The requesting origin is what the app key is bound to
+    // (and what the query's `appUrl` is validated against), so it is required;
+    // the query itself is validated here (`appConnectRequestOf` throws on a
+    // malformed `app` block), so the processor only ever sees a well-formed
+    // request whose `appUrl` is already in serialized form.
+    if (hasAppConnectQuery(queries)) {
+        if (!processors?.processAppConnect) {
+            throw new Error('An App Connect request was received but no processAppConnect ' +
+                'processor was provided.');
+        }
+        if (!credentialRequestOrigin) {
+            throw new Error('An App Connect request requires a requesting origin.');
+        }
+        const appConnect = appConnectRequestOf({
+            queries,
+            origin: credentialRequestOrigin
+        });
+        if (!appConnect) {
+            throw new Error('An AppConnectQuery could not be classified.');
+        }
+        return processors.processAppConnect({
+            request,
+            appConnect,
+            origin: credentialRequestOrigin,
+            challenge,
+            domain,
+            didAuthRequested: didAuth,
+            cryptosuite: negotiatedCryptosuite
+        });
+    }
+    // Delegate the approved capabilities first, then embed them in the VP.
+    const zcaps = zcapRequests.length > 0 && processors?.processZcaps
+        ? await processors.processZcaps({ zcapRequests })
+        : [];
+    if (!didAuth && selectedVCs.length === 0 && zcaps.length === 0) {
+        // Nothing to send: no DID Auth, no VCs, and no satisfiable grants.
+        return {};
+    }
+    const verifiablePresentation = await composeVp({
+        presentationSigner,
+        selectedVcs: selectedVCs,
+        challenge,
+        domain,
+        didAuthRequested: didAuth,
+        cryptosuite: negotiatedCryptosuite,
+        zcaps
+    });
+    // Return the delegated capabilities alongside the VP so the caller can log
+    // exactly what was granted from these objects, rather than reading them back
+    // off the composed VP.
+    return { verifiablePresentation, zcaps };
+}
+//# sourceMappingURL=processRequest.js.map

package/dist/processRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processRequest.js","sourceRoot":"","sources":["../src/processRequest.ts"],"names":[],"mappings":"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"}

package/dist/queryPredicates.d.ts

@@ -0,0 +1,112 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Import-free helpers shared by the request classifiers: which VPR query
+ * type a query object carries, and the parse-and-no-fragment core every URL
+ * validated straight off a request body layers its own rule on top of. Kept
+ * in one dependency-light leaf file so `onboarding.ts` can classify a
+ * `WalletOnboardingQuery` without pulling `classify.ts`'s heavier graph.
+ */
+import type { IVPRQuery, IZcapQuery } from './types.js';
+/**
+ * Whether a query is a standalone capability query, under either type string:
+ * `AuthorizationCapabilityQuery` (the canonical VCALM spelling) or the legacy
+ * `ZcapQuery`.
+ *
+ * The one reader of that alias pair. Both exclusivity checks and both
+ * capability extractors ask through here, so retiring or extending the pair
+ * is one edit rather than four.
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export declare function isZcapQuery(query: IVPRQuery): query is IZcapQuery;
+/**
+ * The query types that stand alone in a request under the
+ * one-mental-model-per-exchange rule: a screen that asks the person to
+ * connect a wallet, or to join an account, must not simultaneously ask them
+ * to share credentials or grant capabilities. Each type excludes
+ * `QueryByExample`, standalone capability queries, and every other member of
+ * this set, in both directions. The set is the one home of that mutual
+ * exclusion: adding a third exclusive type is one entry here, and
+ * {@link exclusiveQueryOf} refuses the new mixtures from every side.
+ */
+export declare const EXCLUSIVE_QUERY_TYPES: readonly ["AppConnectQuery", "WalletOnboardingQuery"];
+/**
+ * A member of {@link EXCLUSIVE_QUERY_TYPES}.
+ */
+export type ExclusiveQueryType = (typeof EXCLUSIVE_QUERY_TYPES)[number];
+/**
+ * Whether a query is an `AppConnectQuery`. Callers filtering on this still
+ * cast the result to `IAppConnectQuery[]` (see {@link isQueryOfType}).
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export declare function isAppConnectQuery(query: IVPRQuery): boolean;
+/**
+ * Whether a query set carries an `AppConnectQuery` at all: the gate
+ * `processRequest` takes its App Connect branch on, and the presence half of
+ * `appConnectRequestOf`'s extraction. The gate cannot simply run the
+ * extractor, since the extractor needs the requesting origin whose absence
+ * the gate must report, so the two share this predicate instead of each
+ * filtering on the type string.
+ *
+ * @param queries {IVPRQuery[]}
+ * @returns {boolean}
+ */
+export declare function hasAppConnectQuery(queries: IVPRQuery[]): boolean;
+/**
+ * Whether a query is a `WalletOnboardingQuery`. Matched the same way as
+ * {@link isAppConnectQuery}.
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export declare function isWalletOnboardingQuery(query: IVPRQuery): boolean;
+/**
+ * The singleton query of a set for one of the {@link EXCLUSIVE_QUERY_TYPES}.
+ * Returns `null` when no query of the type is present, the one query when
+ * exactly one is, and throws when more than one appears or when a query of a
+ * mutually exclusive type sits beside it: `QueryByExample`, a standalone
+ * capability query, or any other exclusive type. The exclusion list is
+ * derived from the shared set rather than written per caller, so no type can
+ * be excluded from one direction only.
+ *
+ * @param options {object}
+ * @param options.queries {IVPRQuery[]}   the request's query set
+ * @param options.typeName {ExclusiveQueryType}   the singleton's type
+ * @returns {IVPRQuery | null}
+ */
+export declare function exclusiveQueryOf({ queries, typeName }: {
+    queries: IVPRQuery[];
+    typeName: ExclusiveQueryType;
+}): IVPRQuery | null;
+/**
+ * Parses a wire value as an absolute URL with no fragment: the shared core
+ * every request field that copies a URL verbatim from an untrusted body
+ * layers its own rule on top of (an App Connect `appUrl`'s same-origin check,
+ * a wallet-onboarding `host`'s http(s)-only check). Throws a caller-supplied
+ * message on a parse failure (with the parse error as `cause`) or on a
+ * fragment, so each site keeps its own wording while the parse-and-no-
+ * fragment logic is written once.
+ *
+ * The fragment check reads the serialized URL rather than `url.hash`: a bare
+ * trailing `#` sets an empty (non-null) fragment that `hash` reports as `''`,
+ * and a percent-encoded `%23` never appears as `#` in the serialization.
+ *
+ * @param options {object}
+ * @param options.value {string}   the raw wire value to parse
+ * @param options.notAbsoluteMessage {string}   thrown, with the parse error
+ *   as `cause`, when `value` does not parse as an absolute URL
+ * @param options.fragmentMessage {string}   thrown when the parsed URL
+ *   carries a fragment
+ * @returns {URL}   the parsed URL
+ */
+export declare function parsedAbsoluteUrl({ value, notAbsoluteMessage, fragmentMessage }: {
+    value: string;
+    notAbsoluteMessage: string;
+    fragmentMessage: string;
+}): URL;
+//# sourceMappingURL=queryPredicates.d.ts.map

package/dist/queryPredicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryPredicates.d.ts","sourceRoot":"","sources":["../src/queryPredicates.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,IAAI,UAAU,CAIjE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,uDAGxB,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAwBvE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEjE;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,OAAO,EACP,QAAQ,EACT,EAAE;IACD,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,QAAQ,EAAE,kBAAkB,CAAA;CAC7B,GAAG,SAAS,GAAG,IAAI,CAuBnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,kBAAkB,EAClB,eAAe,EAChB,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,CAAA;CACxB,GAAG,GAAG,CAWN"}

package/dist/queryPredicates.js

@@ -0,0 +1,157 @@
+/**
+ * Whether a query is a standalone capability query, under either type string:
+ * `AuthorizationCapabilityQuery` (the canonical VCALM spelling) or the legacy
+ * `ZcapQuery`.
+ *
+ * The one reader of that alias pair. Both exclusivity checks and both
+ * capability extractors ask through here, so retiring or extending the pair
+ * is one edit rather than four.
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export function isZcapQuery(query) {
+    return (query.type === 'AuthorizationCapabilityQuery' || query.type === 'ZcapQuery');
+}
+/**
+ * The query types that stand alone in a request under the
+ * one-mental-model-per-exchange rule: a screen that asks the person to
+ * connect a wallet, or to join an account, must not simultaneously ask them
+ * to share credentials or grant capabilities. Each type excludes
+ * `QueryByExample`, standalone capability queries, and every other member of
+ * this set, in both directions. The set is the one home of that mutual
+ * exclusion: adding a third exclusive type is one entry here, and
+ * {@link exclusiveQueryOf} refuses the new mixtures from every side.
+ */
+export const EXCLUSIVE_QUERY_TYPES = [
+    'AppConnectQuery',
+    'WalletOnboardingQuery'
+];
+/**
+ * Whether a query carries the given `type` string. The one comparison every
+ * type test in this file runs through: `AppConnectQuery` and
+ * `WalletOnboardingQuery` extend the spec query union rather than being part
+ * of it, so they are matched by `type` string and upcast rather than narrowed
+ * via a type predicate.
+ *
+ * @param options {object}
+ * @param options.query {IVPRQuery}
+ * @param options.typeName {string}
+ * @returns {boolean}
+ */
+function isQueryOfType({ query, typeName }) {
+    return query.type === typeName;
+}
+/**
+ * Whether a query is an `AppConnectQuery`. Callers filtering on this still
+ * cast the result to `IAppConnectQuery[]` (see {@link isQueryOfType}).
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export function isAppConnectQuery(query) {
+    return isQueryOfType({ query, typeName: 'AppConnectQuery' });
+}
+/**
+ * Whether a query set carries an `AppConnectQuery` at all: the gate
+ * `processRequest` takes its App Connect branch on, and the presence half of
+ * `appConnectRequestOf`'s extraction. The gate cannot simply run the
+ * extractor, since the extractor needs the requesting origin whose absence
+ * the gate must report, so the two share this predicate instead of each
+ * filtering on the type string.
+ *
+ * @param queries {IVPRQuery[]}
+ * @returns {boolean}
+ */
+export function hasAppConnectQuery(queries) {
+    return queries.some(isAppConnectQuery);
+}
+/**
+ * Whether a query is a `WalletOnboardingQuery`. Matched the same way as
+ * {@link isAppConnectQuery}.
+ *
+ * @param query {IVPRQuery}
+ * @returns {boolean}
+ */
+export function isWalletOnboardingQuery(query) {
+    return isQueryOfType({ query, typeName: 'WalletOnboardingQuery' });
+}
+/**
+ * The indefinite article a type name takes in a refusal message.
+ *
+ * @param typeName {string}
+ * @returns {string}
+ */
+function articleFor(typeName) {
+    return /^[AEIOU]/.test(typeName) ? 'an' : 'a';
+}
+/**
+ * The singleton query of a set for one of the {@link EXCLUSIVE_QUERY_TYPES}.
+ * Returns `null` when no query of the type is present, the one query when
+ * exactly one is, and throws when more than one appears or when a query of a
+ * mutually exclusive type sits beside it: `QueryByExample`, a standalone
+ * capability query, or any other exclusive type. The exclusion list is
+ * derived from the shared set rather than written per caller, so no type can
+ * be excluded from one direction only.
+ *
+ * @param options {object}
+ * @param options.queries {IVPRQuery[]}   the request's query set
+ * @param options.typeName {ExclusiveQueryType}   the singleton's type
+ * @returns {IVPRQuery | null}
+ */
+export function exclusiveQueryOf({ queries, typeName }) {
+    const matches = queries.filter(query => isQueryOfType({ query, typeName }));
+    if (matches.length === 0) {
+        return null;
+    }
+    if (matches.length > 1) {
+        throw new Error(`More than one ${typeName} found, exiting.`);
+    }
+    const otherTypes = EXCLUSIVE_QUERY_TYPES.filter(other => other !== typeName);
+    const isExcluded = (query) => query.type === 'QueryByExample' ||
+        isZcapQuery(query) ||
+        otherTypes.includes(query.type);
+    if (queries.some(isExcluded)) {
+        const others = otherTypes.map(other => `${articleFor(other)} ${other}`);
+        const article = articleFor(typeName);
+        const capitalized = article[0].toUpperCase() + article.slice(1);
+        throw new Error(`${capitalized} ${typeName} cannot be combined with QueryByExample, ` +
+            `standalone capability queries, or ${others.join(', or ')}.`);
+    }
+    return matches[0];
+}
+/**
+ * Parses a wire value as an absolute URL with no fragment: the shared core
+ * every request field that copies a URL verbatim from an untrusted body
+ * layers its own rule on top of (an App Connect `appUrl`'s same-origin check,
+ * a wallet-onboarding `host`'s http(s)-only check). Throws a caller-supplied
+ * message on a parse failure (with the parse error as `cause`) or on a
+ * fragment, so each site keeps its own wording while the parse-and-no-
+ * fragment logic is written once.
+ *
+ * The fragment check reads the serialized URL rather than `url.hash`: a bare
+ * trailing `#` sets an empty (non-null) fragment that `hash` reports as `''`,
+ * and a percent-encoded `%23` never appears as `#` in the serialization.
+ *
+ * @param options {object}
+ * @param options.value {string}   the raw wire value to parse
+ * @param options.notAbsoluteMessage {string}   thrown, with the parse error
+ *   as `cause`, when `value` does not parse as an absolute URL
+ * @param options.fragmentMessage {string}   thrown when the parsed URL
+ *   carries a fragment
+ * @returns {URL}   the parsed URL
+ */
+export function parsedAbsoluteUrl({ value, notAbsoluteMessage, fragmentMessage }) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (err) {
+        throw new Error(notAbsoluteMessage, { cause: err });
+    }
+    if (url.href.includes('#')) {
+        throw new Error(fragmentMessage);
+    }
+    return url;
+}
+//# sourceMappingURL=queryPredicates.js.map

package/dist/queryPredicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryPredicates.js","sourceRoot":"","sources":["../src/queryPredicates.ts"],"names":[],"mappings":"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"}