@polpo-ai/connect 0.15.144 → 0.16.1

package/README.md

@@ -2,6 +2,15 @@
 
 Shared contracts and client SDK for Polpo Connect.
 
+Custom tool slots support both `gateway` and `legacy_credentials` (the omitted
+mode's compatibility meaning). Gateway code calls `require(slot).request()`;
+approved direct code uses `getToken()`, `getKey()` or `getHeaders()`, for example
+with Git or HMAC libraries. Host policies receive `connectionSlot: { name, mode }`
+on authorization and rechecks and can require separate credential-export consent.
+Declaring a mode never grants access or enables fallback after a denial. Direct
+credentials retain their provider permissions; revocation stops future delivery
+but cannot recall an already copied credential. Keep secrets out of tool results.
+
 Polpo Connect models external service connections as scoped, revocable capabilities that can be assigned to agents without exposing raw access tokens to the model.
 
 This package contains:
@@ -14,33 +23,206 @@ This package contains:
 
 Server-side OAuth/token lifecycle lives in `@polpo-ai/connect-server`.
 
-## Application capabilities
+## Domain model
+
+- A version 2 `ConnectorDefinition` declares `http_api` or `mcp`, supported
+  authentication methods, scopes, operations and policy. It contains no client
+  secret, API key or account token.
+- A Connection selects one `authenticationId` and represents an authorized
+  account. Its owner, audience, scopes, binding and grants remain distinct.
+- An OAuth Client is the registered application used to obtain authorization.
+  Operator/customer/managed ownership does not determine whether an account is
+  shared or belongs to an end user.
+
+`normalizeConnectorDefinition` validates and copies authored definitions.
+`createConnectorRegistry` accepts both old providers and version 2 definitions.
+`catalog()` describes protocol and supported authentication separately. Legacy
+generic API keys with no destination policy are classified as credentials.
+`list()` remains a compatibility projection of each Connector's default method.
+
+## Creating static and MCP Connections
+
+`createApiKeyConnection`, `createPublicConnection`, `createMcpConnection` and
+`startMcpOAuth` accept trusted `audience`, `subject` and `binding`. Omitting
+`audience` retains the shared default; a human owner does not implicitly make an
+account personal. Set `personal` with a `user` owner or `end_user` with an
+`external_user` owner containing both `namespace` and `id`. The service derives
+the principal binding and rejects conflicting or malformed constraints before
+storing credentials or starting consent. Shared accounts can still have narrower
+tenant/resource bindings.
+
+For Cloud, use `createProjectApiKeyConnection`, `createProjectPublicConnection`,
+`createProjectMcpConnection` and `startProjectMcpOAuth`. For a self-hosted server,
+the unsuffixed methods target `/v1/connect`; MCP OAuth requires an explicit
+registered `redirectUri`. `inspectMcpOAuth` inspects a self-hosted endpoint's
+OAuth configuration. All creation methods are authenticated control-plane calls,
+not tools exposed to the model or unauthenticated application users.
+
+Choose a custom MCP's `providerId` and `authenticationId` explicitly. Its selected
+method determines credential injection, including the header name. Generic MCP
+supports public, bearer or a validated `headerName` with `auth: "header"`.
+Discovery inventory is recorded by the host: caller-supplied `discoveredTools`
+and `lastDiscoveredAt` metadata cannot install callable tools.
+
+CLI: `polpo connections create <public|api-key|mcp> ./connection.json` sends the
+same request to the linked project. Store credential-bearing input in a private
+file outside source control; the command prints only the non-secret result.
+`polpo connections mcp connect` opens the dashboard for review and consent. It
+accepts a catalog ID or clean HTTPS endpoint, with optional `--name`,
+`--transport` and `--dashboard-url`. It rejects advanced authentication, owner,
+audience, binding and scope flags because the handoff link cannot carry those
+contracts. Use the session-authenticated MCP OAuth API or a trusted setup session
+when that context is required.
+
+## Agent capabilities
+
+HTTP action handlers receive an authorized `ConnectorActionGateway`. They pass
+an operation and required scopes; the host binds the Connection, trusted user,
+tenant and grants and injects credentials outside the model and tool arguments.
+MCP uses its native transport and discovery. The presence of legacy token and
+application-capability helpers is not an invitation to make Polpo a general
+backend integration broker; the current product scope is agent capabilities.
+
+The host can set the trusted selector's `audience` to select a shared, personal
+or end-user account explicitly. Shared capabilities retain the caller's identity
+for audit. They are not a fallback for a missing end-user match. Legacy records
+without audience remain shared while retaining their binding restrictions.
+
+For a distributed sandbox relay, `getConnectionCapabilitySelection(capability)`
+returns a host-only selection snapshot from the acquired gateway capability.
+Persist it in trusted server state and pass it as `selection` when constructing
+the resolver for subsequent relay requests. Resume loads only that installation
+and rechecks its identity, binding, audience, credential generation and live
+permissions. The snapshot is kept in a WeakMap rather than capability properties;
+never copy it into a tool's arguments, metadata or sandbox payload. A relay claim
+without a selection must be reacquired, not resolved to a replacement account.
+
+## OAuth setup without a required hosted page
+
+Create a setup session from a trusted backend, deriving `subject` and `binding`
+from the application's authenticated user. Never copy an unverified browser
+user ID into this context or put a Polpo API key in browser code.
+
+For the generic OSS API, use `createSetupSession` then `startOAuthSetup(id)`.
+For Cloud, use `createProjectSetupSession(projectId, input)` and
+`startProjectOAuthSetup(token)`. These helpers intentionally target different
+host routes. Cloud may also return a convenience `setupUrl`; opening that page
+is optional. Both paths lead to the same provider-hosted consent.
+
+Cloud control-plane methods use a platform API key supplied through the client's
+`headers: { Authorization: "Bearer ..." }`; the constructor has no `apiKey` or
+`projectId` option. Keep this key on the trusted backend.
+`getSetupStatus`, `cancelSetupSession`, and `waitForSetupCompletion` work with
+both hosts. The OSS router exposes `GET /connect/setup/:id/status` and
+`POST /connect/setup/:id/cancel` under its existing authenticated API; Cloud
+exposes the hosted bearer-link routes. Configure the client's base URL for its
+host. A browser redirect alone never proves completion.
 
-Application backends should invoke a logical capability, not select or receive a
-physical Connection ID. Configure the mapping in the trusted control plane,
-then call it with a project API key:
+Setup-link expiry limits when authorization can start. Once started, status uses
+the OAuth authorization deadline. Cancellation is allowed only before start;
+completed, cancelled and failed outcomes remain terminal after expiry.
+
+Managed clients show the provider's registered Polpo app identity. Customer
+clients show the customer's registered identity. In both cases the host handles
+the provider callback, exchanges the code, and retains tokens server-side.
+The approved application `returnUrl` is separate from that callback. Confirm
+completion through setup status, not a success parameter supplied by a browser.
+
+Cloud project administrators can configure application destinations independently
+of OAuth app ownership using `configureProjectSetup(projectId, { returnOrigins:
+["https://app.example.com"] })` and inspect them with
+`getProjectSetupConfiguration(projectId)`. Origins must use HTTPS and cannot include
+paths or wildcards. The CLI equivalents are `polpo connections setup-config show`
+and `polpo connections setup-config set --origin https://app.example.com` (or
+`--clear`). This configures the application's completion destination, not the
+provider's callback. Removing the last approval for an origin invalidates pending
+flows using it; an OAuth client's or host's separate origin approvals still apply.
+
+After setup, a trusted backend can list and revoke an external user's accounts:
 
 ```ts
-import { PolpoConnectClient } from "@polpo-ai/connect/client";
-
-const connect = new PolpoConnectClient({
-  baseUrl: "https://api.polpo.sh",
-  headers: { authorization: `Bearer ${process.env.POLPO_API_KEY}` },
-});
-
-const response = await connect.requestApplicationCapability(
-  process.env.POLPO_PROJECT_ID!,
-  "github.repositories",
-  {
-    invocation: {
-      user: "customer-42",
-      metadata: { tenantId: "tenant-7" },
-      scope: { key: "workspace-9", version: "3" },
-    },
-    request: { method: "GET", path: "/user/repos" },
-  },
-);
+const owner = { namespace: "my-app", id: authenticatedUser.id };
+const accounts = await connect.listProjectEndUserConnections(projectId, owner);
+await connect.revokeProjectEndUserConnection(projectId, owner, connectionId);
 ```
 
-Unsafe methods require an idempotency key. Runtime request bodies never accept
-a physical Connection ID or provider credential.
+Revocation targets one Connection within that exact project, namespace and user.
+The CLI equivalents are `polpo connections end-users list <user-id> --namespace
+my-app` and `polpo connections end-users revoke <user-id> <connection-id>
+--namespace my-app`. These are authenticated management operations, not public
+browser endpoints.
+
+Agent runtime selection uses that same namespaced identity. Supply the trusted
+principal as `{ type: "external_user", namespace: "my-app", id: userId }`; an ID
+without its application namespace cannot authorize an end-user account. In Cloud
+completion context, the trusted backend supplies `user` and
+`metadata.connectionNamespace`, or the full principal in
+`metadata.connectionScope.principal`. Never derive the namespace from the model,
+provider, email address or an unverified browser parameter. Existing namespaced
+owners remain usable even if their older stored binding omits the namespace;
+records without a valid external-user owner require explicit correction or setup.
+
+For a Connector with multiple authentication methods, pass `authenticationId`
+when configuring a project or organization OAuth client. Pass the same method
+as the optional third argument to `revokeProjectOAuthClient` or
+`revokeOrganizationOAuthClient`. CLI `connections oauth-clients set` and `revoke`
+accept `--authentication <id>`. Omitting it preserves the default method.
+
+## Custom definitions and verification
+
+`registerConnectorDefinition` registers a validated custom definition on a host
+with a `ConnectorDefinitionStore`. IDs are immutable: changing endpoint policy
+requires a new definition and explicit setup, so existing secrets cannot be
+silently redirected. `disableConnectorDefinition` blocks subsequent use.
+The store must be scoped to the authorized tenant by the host.
+
+For Cloud, use `listProjectCatalog(projectId)`,
+`registerProjectConnectorDefinition(projectId, definition)`, and
+`disableProjectConnectorDefinition(projectId, connectorId)`. The CLI exposes
+`connections connectors register <file>` and `connections connectors disable <id>`.
+
+`getSetupReadiness(input)` checks local prerequisites for the selected
+authentication and OAuth Client mode. It reports configuration readiness only:
+`consent_required` does not claim a working authorization, and
+`credentials_required` does not validate a key. Use `verifyConnection` after
+setup for a live check. The managed/own label describes app ownership, not
+availability or connection health.
+
+The Cloud variant is `getProjectSetupReadiness(projectId, { providerId,
+authenticationId, oauthClientMode })`. Its CLI equivalent is `connections
+setup-readiness <provider-id> --authentication <id> --oauth-client-mode managed`.
+This checks setup prerequisites; `connections readiness` instead checks a
+specific runtime slot's trusted selection and grants.
+
+`verifyConnection(id)` returns `passed`, `failed`, `inconclusive`, or
+`unsupported`, with check type, timestamp and configuration/credential versions.
+A successful public operation does not verify a credential. MCP discovery does
+not prove that every discovered tool works. Verification is independent of the
+Connection lifecycle and must not silently revoke it. Project hosts use
+`verifyProjectConnection(projectId, id)` and must implement the matching route.
+## Account assignment preflight
+
+Hosts can validate account assignments for a logical capability with
+`validateConnectionAssignments([{ connection, binding }])`. The optional binding
+adds grant constraints to the Connection's own binding. The result is `{ ok:
+true }` or a non-secret conflict with `reason` and `connectionIds`.
+
+Different accounts need disjoint trusted contexts. Personal ownership constrains
+the principal; missing fields do not disambiguate accounts. The host must select
+the audience explicitly and must still enforce visibility, active status,
+scopes, grants, and concurrent-write protection. This configuration check does
+not replace the runtime resolver's exact-one-account authorization.
+
+
+MCP reusable client configuration is described by `ResolvedMcpOAuthClient` and
+`McpOAuthClientResolver`. These host-only contracts distinguish configuration
+ownership from the protocol's three registration methods. They do not expose
+provider secrets to the setup SDK. An OSS host with `mcpOAuthClients`, setup/link
+stores and atomic embedded persistence supports MCP through `createSetupSession`:
+pass `configurationId` to select the approved reusable configuration. The same
+selector is available on `CreateConnectionSetupSessionRequest`, the OSS HTTP
+setup endpoint, and `polpo connections setup-session --configuration <id>`.
+The request assigns a trusted owner and audience; the browser receives a setup
+token, not the client secret. Callback completion creates that owner's account,
+its project link and both receipts atomically. Managed hosts must implement and
+deploy the same server capability before accepting MCP on their setup route.

package/dist/assignment-policy.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectionBindingAttributes, ConnectionRecord } from "./types.js";
+/** A prospective assignment for one capability. Hosts supply only active,
+ * visible accounts and must also check scopes, grants and execution surfaces. */
+export interface ConnectionAssignment {
+    connection: Pick<ConnectionRecord, "id" | "providerId" | "audience" | "owner" | "binding">;
+    /** Additional grant constraints. They never replace account constraints. */
+    binding?: ConnectionBindingAttributes;
+}
+export type ConnectionAssignmentValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_context" | "provider_mismatch" | "overlapping_context";
+    connectionIds: string[];
+};
+/** Configuration preflight, not runtime authorization or a write lock. Distinct
+ * accounts may coexist only when no explicit trusted selector can match both.
+ * Hosts that cannot select an audience explicitly must additionally restrict
+ * assignments to one audience. Runtime must still reject ambiguous selection. */
+export declare function validateConnectionAssignments(assignments: readonly ConnectionAssignment[]): ConnectionAssignmentValidation;
+//# sourceMappingURL=assignment-policy.d.ts.map

package/dist/assignment-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment-policy.d.ts","sourceRoot":"","sources":["../src/assignment-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhF;iFACiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC3F,4EAA4E;IAC5E,OAAO,CAAC,EAAE,2BAA2B,CAAC;CACvC;AAED,MAAM,MAAM,8BAA8B,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAC1D,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;IACxE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;;iFAGiF;AACjF,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAAG,8BAA8B,CAiB1H"}

package/dist/assignment-policy.js

@@ -0,0 +1,93 @@
+/** Configuration preflight, not runtime authorization or a write lock. Distinct
+ * accounts may coexist only when no explicit trusted selector can match both.
+ * Hosts that cannot select an audience explicitly must additionally restrict
+ * assignments to one audience. Runtime must still reject ambiguous selection. */
+export function validateConnectionAssignments(assignments) {
+    const contexts = [];
+    for (const assignment of assignments) {
+        const fields = contextConstraints(assignment);
+        if (!fields)
+            return { ok: false, reason: "invalid_context", connectionIds: [assignment.connection.id] };
+        for (const previous of contexts) {
+            const ids = [previous.assignment.connection.id, assignment.connection.id];
+            if (previous.assignment.connection.providerId !== assignment.connection.providerId) {
+                return { ok: false, reason: "provider_mismatch", connectionIds: ids };
+            }
+            if (ids[0] === ids[1])
+                continue; // Several grants may authorize the same account.
+            const disjoint = [...fields].some(([key, value]) => previous.fields.has(key) && previous.fields.get(key) !== value);
+            if (!disjoint)
+                return { ok: false, reason: "overlapping_context", connectionIds: ids };
+        }
+        contexts.push({ assignment, fields });
+    }
+    return { ok: true };
+}
+const bindingParts = {
+    principal: ["type", "id", "namespace"],
+    tenant: ["namespace", "id"],
+    resource: ["namespace", "type", "id"],
+};
+function contextConstraints({ connection, binding }) {
+    const fields = new Map();
+    const audience = connection.audience ?? "shared";
+    if (!["personal", "shared", "end_user"].includes(audience))
+        return;
+    fields.set("audience", audience);
+    const add = (key, value) => {
+        // Selector normalization trims values; whitespace-bearing persisted values
+        // cannot reliably identify a reachable account.
+        if (typeof value !== "string" || !value || value.trim() !== value)
+            return false;
+        if (fields.has(key) && fields.get(key) !== value)
+            return false;
+        fields.set(key, value);
+        return true;
+    };
+    const merge = (value, requireConstraint) => {
+        if (value === undefined)
+            return true;
+        if (!plainObject(value) || (requireConstraint && Object.keys(value).length === 0))
+            return false;
+        for (const [key, part] of Object.entries(value)) {
+            if (key === "scopeEpoch") {
+                if (!add(key, part))
+                    return false;
+            }
+            else {
+                if (!Object.hasOwn(bindingParts, key))
+                    return false;
+                const allowed = bindingParts[key];
+                if (!allowed || !plainObject(part) || Object.keys(part).length === 0)
+                    return false;
+                for (const [field, text] of Object.entries(part)) {
+                    if (!allowed.includes(field) || !add(`${key}.${field}`, text))
+                        return false;
+                }
+            }
+        }
+        return true;
+    };
+    if (!merge(connection.binding, true) || !merge(binding, false))
+        return;
+    if (audience === "personal") {
+        if (connection.owner?.type !== "user" || !add("principal.type", "user") || !add("principal.id", connection.owner.id))
+            return;
+    }
+    if (audience === "end_user") {
+        // End-user identity must be carried by the Connection itself, not rescued
+        // by a grant. Partial legacy fields still constrain shared installations.
+        const principal = connection.binding?.principal;
+        const owner = connection.owner;
+        if (owner?.type !== "external_user" || principal?.type !== "external_user" || principal.id !== owner.id
+            || !add("principal.type", "external_user") || !add("principal.id", owner.id)
+            || !add("principal.namespace", owner.namespace))
+            return;
+    }
+    return fields;
+}
+function plainObject(value) {
+    return value !== null && typeof value === "object"
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+//# sourceMappingURL=assignment-policy.js.map

package/dist/assignment-policy.js.map

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

package/dist/capability-resolver.d.ts

@@ -1,16 +1,60 @@
-import { type ConnectionCapabilityResolver, type ConnectionCapabilityResolveInput, type ConnectionRequest, type ConnectionResponse, type ApplicationCapabilityResolveInput, type ApplicationCapabilityResolver } from "@polpo-ai/core";
-import type { ConnectionRecord, ConnectionSelectionSelector, ConnectPolicy, ConnectStore, ResolvedConnectionCredential } from "./types.js";
+import { type AgentSnapshot, type ConnectionCapabilityResolver, type ConnectionCapabilityResolveInput, type ConnectionRequest, type ConnectionResponse, type ResolvedConnectionCapability, type ApplicationCapabilityResolveInput, type ApplicationCapabilityResolver } from "@polpo-ai/core";
+import type { ConnectionBindingAttributes, ConnectionRecord, ConnectionSelectionSelector, ConnectPolicy, ConnectStore, ResolvedConnectionCredential } from "./types.js";
 export interface ConnectionCapabilityResolverOptions {
     store: ConnectStore;
+    /** Agent-scoped hosts must provide this live lookup. The expected identity
+     * comes only from the invocation captured with the execution config. */
+    getAgentSnapshot?(name: string): Promise<AgentSnapshot | undefined>;
+    /** Trusted host state for resuming an acquired capability. Never take this from tool arguments. */
+    selection?: ConnectionCapabilitySelection;
     resolveSelector(input: ConnectionCapabilityResolveInput): ConnectionSelectionSelector | Promise<ConnectionSelectionSelector>;
     materialize?(connection: ConnectionRecord, input: ConnectionCapabilityResolveInput): ResolvedConnectionCredential | Promise<ResolvedConnectionCredential>;
-    request?<T = unknown>(connection: ConnectionRecord, input: ConnectionCapabilityResolveInput, request: ConnectionRequest): Promise<ConnectionResponse<T>>;
+    request?<T = unknown>(connection: ConnectionRecord, input: ConnectionCapabilityResolveInput, request: ConnectionRequest, 
+    /** Call after refresh/DNS waits and before each credential-bearing dispatch. */
+    reauthorize: () => Promise<void>): Promise<ConnectionResponse<T>>;
     isConnectionVisible?(connection: ConnectionRecord, selector: ConnectionSelectionSelector): boolean | Promise<boolean>;
     policy?: ConnectPolicy;
 }
+/** Stored only by the host. It is deliberately absent from tool-visible capability properties. */
+export interface ConnectionCapabilitySelection {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly audience: "personal" | "shared" | "end_user";
+    readonly secretRef?: string;
+    readonly credentialVersion?: string;
+    readonly bindingKey: string;
+}
+/** Host-only delivery guard. Rechecks the acquired account, grant, identity
+ * and credential installation without switching selection or rematerializing
+ * secrets. Never serialize this guard into a tool or sandbox capability. */
+export declare function assertConnectionCapabilityAuthorized(capability: ResolvedConnectionCapability): Promise<void>;
+export declare function getConnectionCapabilitySelection(capability: ResolvedConnectionCapability): ConnectionCapabilitySelection | undefined;
+/** Host-only snapshot for durable delegation. Never expose this to tools or
+ * copy it into a sandbox: it includes credential installation references. */
+export declare function snapshotConnectionCapabilitySelection(connection: ConnectionRecord): ConnectionCapabilitySelection;
+export declare function matchesConnectionCapabilitySelection(connection: ConnectionRecord, expected: ConnectionCapabilitySelection): boolean;
 export interface ApplicationCapabilityResolverOptions extends Omit<ConnectionCapabilityResolverOptions, "resolveSelector"> {
     resolveSelector(input: ApplicationCapabilityResolveInput): ConnectionSelectionSelector | Promise<ConnectionSelectionSelector>;
 }
+/** Legacy installations are shared; ownership is never inferred from binding fields. */
+export declare function effectiveConnectionAudience(connection: ConnectionRecord): import("./types.js").ConnectionAudience;
+/** Grant bindings are additional constraints, not standalone account identities. */
+export declare function matchesConnectionBindingAttributes(binding: ConnectionBindingAttributes | undefined, selector: ConnectionSelectionSelector): boolean;
+/** Match account ownership and binding against a host-created selector. No fallback is performed. */
+export declare function matchesConnectionBinding(connection: ConnectionRecord, selector: ConnectionSelectionSelector): boolean;
+/** Host-only authorization shared by HTTP and MCP. No credentials or protocol
+ * operations are exposed here; consumers must call current() before transport use. */
+export interface SelectedConnectionAccess {
+    readonly input: ConnectionCapabilityResolveInput;
+    readonly connection: ConnectionRecord;
+    readonly selection: ConnectionCapabilitySelection;
+    current(): Promise<ConnectionRecord>;
+    dispose(): void;
+}
+export type ConnectionAccessResolverOptions = Pick<ConnectionCapabilityResolverOptions, "store" | "selection" | "resolveSelector" | "isConnectionVisible" | "policy" | "getAgentSnapshot">;
+export declare function createConnectionAccessResolver(options: ConnectionAccessResolverOptions): {
+    acquire(input: ConnectionCapabilityResolveInput): Promise<SelectedConnectionAccess>;
+};
 export declare function createConnectionCapabilityResolver(options: ConnectionCapabilityResolverOptions): ConnectionCapabilityResolver;
 export declare function createApplicationCapabilityResolver(options: ApplicationCapabilityResolverOptions): ApplicationCapabilityResolver;
 //# sourceMappingURL=capability-resolver.d.ts.map

package/dist/capability-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-resolver.d.ts","sourceRoot":"","sources":["../src/capability-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,gCAAgC,EACrC,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAEvB,KAAK,iCAAiC,EACtC,KAAK,6BAA6B,EAEnC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAEV,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,YAAY,EACZ,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mCAAmC;IAClD,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,CACb,KAAK,EAAE,gCAAgC,GACtC,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACtE,WAAW,CAAC,CACV,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,gCAAgC,GACtC,4BAA4B,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACxE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,EAClB,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,gCAAgC,EACvC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,mBAAmB,CAAC,CAClB,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,2BAA2B,GACpC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,oCAAqC,SAAQ,IAAI,CAChE,mCAAmC,EACnC,iBAAiB,CAClB;IACC,eAAe,CACb,KAAK,EAAE,iCAAiC,GACvC,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACvE;AAgJD,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,4BAA4B,CAkG9B;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,6BAA6B,CAoC/B"}
+{"version":3,"file":"capability-resolver.d.ts","sourceRoot":"","sources":["../src/capability-resolver.ts"],"names":[],"mappings":"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"}