@backstage/backend-plugin-api 1.1.1 → 1.2.0-next.0

package/dist/index.d.ts

@@ -1,647 +1,541 @@
 /// <reference types="node" />
-import { Readable } from 'stream';
-import { Config } from '@backstage/config';
 import { JsonObject, HumanDuration, JsonValue } from '@backstage/types';
-import { Duration } from 'luxon';
-import { Handler, Request, Response } from 'express';
-import { PermissionAttributes, EvaluatorRequestOptions, PermissionEvaluator, AuthorizePermissionRequest, AuthorizePermissionResponse, QueryPermissionRequest, QueryPermissionResponse } from '@backstage/plugin-permission-common';
+import { Request, Response, Handler } from 'express';
+import { PermissionAttributes, EvaluatorRequestOptions, PermissionEvaluator, AuthorizePermissionRequest, AuthorizePermissionResponse, QueryPermissionRequest, QueryPermissionResponse, Permission } from '@backstage/plugin-permission-common';
 import { Knex } from 'knex';
+import { PermissionRule } from '@backstage/plugin-permission-node';
+import { Config } from '@backstage/config';
+import { Duration } from 'luxon';
+import { Readable } from 'stream';
 export { isChildPath } from '@backstage/cli-common';
 
 /**
- * A generic interface for fetching plain data from URLs.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/url-reader | service documentation} for more details.
- *
+ * low (default): normal usage
+ * medium: accessing write endpoints
+ * high: non-root permission changes
+ * critical: root permission changes
  * @public
  */
-interface UrlReaderService {
-    /**
-     * Reads a single file and return its content.
-     */
-    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
+type AuditorServiceEventSeverityLevel = 'low' | 'medium' | 'high' | 'critical';
+/** @public */
+type AuditorServiceCreateEventOptions = {
     /**
-     * Reads a full or partial file tree.
+     * Use kebab-case to name audit events (e.g., "user-login", "file-download", "fetch"). Represents a logical group of similar events or operations. For example, "fetch" could be used as an eventId encompassing various fetch methods like "by-id" or "by-location".
+     *
+     * The `pluginId` already provides plugin/module context, so avoid redundant prefixes in the `eventId`.
      */
-    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
+    eventId: string;
+    /** (Optional) The severity level for the audit event. */
+    severityLevel?: AuditorServiceEventSeverityLevel;
+    /** (Optional) The associated HTTP request, if applicable. */
+    request?: Request<any, any, any, any, any>;
     /**
-     * Searches for a file in a tree using a glob pattern.
+     * (Optional) Additional metadata relevant to the event, structured as a JSON object.
+     * This could include a `queryType` field, using kebab-case, for variations within the main event (e.g., "by-id", "by-user").
+     * For example, if the `eventId` is "fetch", the `queryType` in `meta` could be "by-id" or "by-location".
      */
-    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
+    meta?: JsonObject;
+};
+/** @public */
+type AuditorServiceEvent = {
+    success(options?: {
+        meta?: JsonObject;
+    }): Promise<void>;
+    fail(options: {
+        meta?: JsonObject;
+        error: Error;
+    }): Promise<void>;
+};
+/**
+ * A service that provides an auditor facility.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/auditor | service documentation} for more details.
+ *
+ * @public
+ */
+interface AuditorService {
+    createEvent(options: AuditorServiceCreateEventOptions): Promise<AuditorServiceEvent>;
 }
+
 /**
- * An options object for readUrl operations.
+ * Represents a user principal (for example when a user Backstage token issued
+ * by the auth backend was given to a request).
+ *
+ * @remarks
+ *
+ * Additional information about the user can be fetched using the
+ * {@link UserInfoService}.
  *
  * @public
  */
-type UrlReaderServiceReadUrlOptions = {
-    /**
-     * An ETag which can be provided to check whether a
-     * {@link UrlReaderService.readUrl} response has changed from a previous execution.
-     *
-     * @remarks
-     *
-     * In the {@link UrlReaderService.readUrl} response, an ETag is returned along with
-     * the data. The ETag is a unique identifier of the data, usually the commit
-     * SHA or ETag from the target.
-     *
-     * When an ETag is given in ReadUrlOptions, {@link UrlReaderService.readUrl} will
-     * first compare the ETag against the ETag of the target. If they match,
-     * {@link UrlReaderService.readUrl} will throw a
-     * {@link @backstage/errors#NotModifiedError} indicating that the response
-     * will not differ from the previous response which included this particular
-     * ETag. If they do not match, {@link UrlReaderService.readUrl} will return the rest
-     * of the response along with a new ETag.
-     */
-    etag?: string;
-    /**
-     * A date which can be provided to check whether a
-     * {@link UrlReaderService.readUrl} response has changed since the lastModifiedAt.
-     *
-     * @remarks
-     *
-     * In the {@link UrlReaderService.readUrl} response, an lastModifiedAt is returned
-     * along with data. The lastModifiedAt date represents the last time the data
-     * was modified.
-     *
-     * When an lastModifiedAfter is given in ReadUrlOptions, {@link UrlReaderService.readUrl}
-     * will compare the lastModifiedAfter against the lastModifiedAt of the target. If
-     * the data has not been modified since this date, the {@link UrlReaderService.readUrl}
-     * will throw a {@link @backstage/errors#NotModifiedError} indicating that the
-     * response does not contain any new data. If they do not match,
-     * {@link UrlReaderService.readUrl} will return the rest of the response along with new
-     * lastModifiedAt date.
-     */
-    lastModifiedAfter?: Date;
-    /**
-     * An abort signal to pass down to the underlying request.
-     *
-     * @remarks
-     *
-     * Not all reader implementations may take this field into account.
-     */
-    signal?: AbortSignal;
+type BackstageUserPrincipal = {
+    type: 'user';
     /**
-     * An optional token to use for authentication when reading the resources.
-     *
-     * @remarks
-     *
-     * By default all URL Readers will use the integrations config which is supplied
-     * when creating the Readers. Sometimes it might be desireable to use the already
-     * created URLReaders but with a different token, maybe that's supplied by the user
-     * at runtime.
+     * The entity ref of the user entity that this principal represents.
      */
-    token?: string;
+    userEntityRef: string;
 };
 /**
- * A response object for {@link UrlReaderService.readUrl} operations.
+ * Represents a principal that is not authenticated (for example when no token
+ * at all was given to a request).
  *
  * @public
  */
-type UrlReaderServiceReadUrlResponse = {
-    /**
-     * Returns the data that was read from the remote URL.
-     */
-    buffer(): Promise<Buffer>;
+type BackstageNonePrincipal = {
+    type: 'none';
+};
+/**
+ * Represents a service principal (for example when an external access method
+ * token was given to a request, or the caller was a Backstage backend plugin).
+ * @public
+ */
+type BackstageServicePrincipal = {
+    type: 'service';
     /**
-     * Returns the data that was read from the remote URL as a Readable stream.
+     * A string that represents the service.
      *
      * @remarks
      *
-     * This method will be required in a future release.
+     * This string is only informational, has no well defined semantics, and
+     * should never be used to drive actual logic in code.
      */
-    stream?(): Readable;
+    subject: string;
     /**
-     * Etag returned by content provider.
+     * The access restrictions that apply to this principal.
      *
      * @remarks
      *
-     * Can be used to compare and cache responses when doing subsequent calls.
-     */
-    etag?: string;
-    /**
-     * Last modified date of the file contents.
+     * If no access restrictions are provided the principal is assumed to have
+     * unlimited access, at a framework level. The permissions system and
+     * individual plugins may or may not still apply additional access controls on
+     * top of this.
      */
-    lastModifiedAt?: Date;
+    accessRestrictions?: BackstagePrincipalAccessRestrictions;
 };
 /**
- * An options object for {@link UrlReaderService.readTree} operations.
+ * The access restrictions that apply to a given principal.
  *
  * @public
  */
-type UrlReaderServiceReadTreeOptions = {
+type BackstagePrincipalAccessRestrictions = {
     /**
-     * A filter that can be used to select which files should be included.
-     *
-     * @remarks
-     *
-     * The path passed to the filter function is the relative path from the URL
-     * that the file tree is fetched from, without any leading '/'.
+     * If given, the principal is limited to only performing actions with these
+     * named permissions.
      *
-     * For example, given the URL https://github.com/my/repo/tree/master/my-dir, a file
-     * at https://github.com/my/repo/blob/master/my-dir/my-subdir/my-file.txt will
-     * be represented as my-subdir/my-file.txt
+     * Note that this only applies where permissions checks are enabled in the
+     * first place. Endpoints that are not protected by the permissions system at
+     * all, are not affected by this setting.
      *
-     * If no filter is provided, all files are extracted.
+     * This array always has at least one element, or is missing entirely.
      */
-    filter?(path: string, info?: {
-        size: number;
-    }): boolean;
+    permissionNames?: string[];
     /**
-     * An ETag which can be provided to check whether a
-     * {@link UrlReaderService.readTree} response has changed from a previous execution.
-     *
-     * @remarks
+     * If given, the principal is limited to only performing actions whose
+     * permissions have these attributes.
      *
-     * In the {@link UrlReaderService.readTree} response, an ETag is returned along with
-     * the tree blob. The ETag is a unique identifier of the tree blob, usually
-     * the commit SHA or ETag from the target.
+     * Note that this only applies where permissions checks are enabled in the
+     * first place. Endpoints that are not protected by the permissions system at
+     * all, are not affected by this setting.
      *
-     * When an ETag is given as a request option, {@link UrlReaderService.readTree} will
-     * first compare the ETag against the ETag on the target branch. If they
-     * match, {@link UrlReaderService.readTree} will throw a
-     * {@link @backstage/errors#NotModifiedError} indicating that the response
-     * will not differ from the previous response which included this particular
-     * ETag. If they do not match, {@link UrlReaderService.readTree} will return the
-     * rest of the response along with a new ETag.
+     * This object always has at least one key, or is missing entirely.
      */
-    etag?: string;
+    permissionAttributes?: {
+        /**
+         * Match any of these action values. This array always has at least one
+         * element, or is missing entirely.
+         */
+        action?: Array<Required<PermissionAttributes>['action']>;
+    };
+};
+/**
+ * An opaque representation of credentials, for example as passed in a
+ * request-response flow.
+ *
+ * @public
+ */
+type BackstageCredentials<TPrincipal = unknown> = {
+    $$type: '@backstage/BackstageCredentials';
     /**
-     * An abort signal to pass down to the underlying request.
-     *
-     * @remarks
-     *
-     * Not all reader implementations may take this field into account.
+     * If the credentials have a limited lifetime, this is the time at which they
+     * expire and may no longer be accepted by a receiver.
      */
-    signal?: AbortSignal;
+    expiresAt?: Date;
     /**
-     * An optional token to use for authentication when reading the resources.
+     * The principal (originator) of the request.
      *
      * @remarks
      *
-     * By default all URL Readers will use the integrations config which is supplied
-     * when creating the Readers. Sometimes it might be desireable to use the already
-     * created URLReaders but with a different token, maybe that's supplied by the user
-     * at runtime.
+     * This is semantically the originator of a request chain, and may or may not
+     * represent the immediate caller of your service. For example, in
+     * on-behalf-of scenarios, the immediate caller may be an intermediary backend
+     * service, but the principal may still be a user that was the original
+     * caller.
      */
-    token?: string;
+    principal: TPrincipal;
 };
 /**
- * Options that control {@link UrlReaderServiceReadTreeResponse.dir} execution.
+ * The types of principal that can be represented in a
+ * {@link BackstageCredentials} object.
  *
  * @public
  */
-type UrlReaderServiceReadTreeResponseDirOptions = {
-    /**
-     * The directory to write files to.
-     *
-     * @remarks
-     *
-     * Defaults to the OS tmpdir, or `backend.workingDirectory` if set in config.
-     */
-    targetDir?: string;
+type BackstagePrincipalTypes = {
+    user: BackstageUserPrincipal;
+    service: BackstageServicePrincipal;
+    none: BackstageNonePrincipal;
+    unknown: unknown;
 };
 /**
- * A response object for {@link UrlReaderService.readTree} operations.
+ * Provides token authentication and credentials management.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/auth | service documentation} for more details.
  *
  * @public
  */
-type UrlReaderServiceReadTreeResponse = {
+interface AuthService {
     /**
-     * Returns an array of all the files inside the tree, and corresponding
-     * functions to read their content.
+     * Verifies a token and returns the associated credentials.
      */
-    files(): Promise<UrlReaderServiceReadTreeResponseFile[]>;
+    authenticate(token: string, options?: {
+        /**
+         * If set to true, allow limited access tokens (such as cookies).
+         *
+         * If this flag is not set, or is set to false, calls with limited access
+         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+         * thrown.
+         */
+        allowLimitedAccess?: boolean;
+    }): Promise<BackstageCredentials>;
     /**
-     * Returns the tree contents as a binary archive, using a stream.
+     * Checks if the given credentials are of the given type, and narrows the
+     * TypeScript type accordingly if there's a match.
      */
-    archive(): Promise<NodeJS.ReadableStream>;
+    isPrincipal<TType extends keyof BackstagePrincipalTypes>(credentials: BackstageCredentials, type: TType): credentials is BackstageCredentials<BackstagePrincipalTypes[TType]>;
     /**
-     * Extracts the tree response into a directory and returns the path of the
-     * directory.
-     *
-     * **NOTE**: It is the responsibility of the caller to remove the directory after use.
+     * Create a credentials object that represents an unauthenticated caller.
      */
-    dir(options?: UrlReaderServiceReadTreeResponseDirOptions): Promise<string>;
+    getNoneCredentials(): Promise<BackstageCredentials<BackstageNonePrincipal>>;
     /**
-     * Etag returned by content provider.
+     * Create a credentials object that represents the current service itself.
+     */
+    getOwnServiceCredentials(): Promise<BackstageCredentials<BackstageServicePrincipal>>;
+    /**
+     * Issue a token that can be used for authenticating calls towards other
+     * backend plugins.
      *
      * @remarks
      *
-     * Can be used to compare and cache responses when doing subsequent calls.
+     * This method should be called before each request. Do not hold on to the
+     * issued token and reuse it for future calls.
      */
-    etag: string;
-};
-/**
- * Represents a single file in a {@link UrlReaderService.readTree} response.
- *
- * @public
- */
-type UrlReaderServiceReadTreeResponseFile = {
+    getPluginRequestToken(options: {
+        /**
+         * The credentials of the originator of the request.
+         *
+         * @remarks
+         *
+         * This is most commonly the result of
+         * {@link AuthService.getOwnServiceCredentials} when the current service is
+         * the originator, or the output of {@link HttpAuthService.credentials} when
+         * performing requests on behalf of an incoming request identity.
+         */
+        onBehalfOf: BackstageCredentials;
+        /**
+         * The ID of the plugin that the request is being made to.
+         */
+        targetPluginId: string;
+    }): Promise<{
+        token: string;
+    }>;
     /**
-     * The filepath of the data.
+     * Issue a limited user token that can be used e.g. in cookie flows.
      */
-    path: string;
+    getLimitedUserToken(
     /**
-     * The binary contents of the file.
+     * The credentials that this token should represent. Must be a user
+     * principal. Commonly the output of {@link HttpAuthService.credentials} is
+     * used as the input.
      */
-    content(): Promise<Buffer>;
+    credentials: BackstageCredentials<BackstageUserPrincipal>): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
     /**
-     * The last modified timestamp of the data.
+     * Retrieve the public keys that have been used to sign tokens that were
+     * issued by this service. This list is periodically pruned from keys that are
+     * significantly past their expiry.
      */
-    lastModifiedAt?: Date;
-};
+    listPublicServiceKeys(): Promise<{
+        keys: JsonObject[];
+    }>;
+}
+
 /**
- * An options object for search operations.
+ * Options passed to {@link CacheService.set}.
  *
  * @public
  */
-type UrlReaderServiceSearchOptions = {
-    /**
-     * An etag can be provided to check whether the search response has changed from a previous execution.
-     *
-     * In the search() response, an etag is returned along with the files. The etag is a unique identifier
-     * of the current tree, usually the commit SHA or etag from the target.
-     *
-     * When an etag is given in SearchOptions, search will first compare the etag against the etag
-     * on the target branch. If they match, search will throw a NotModifiedError indicating that the search
-     * response will not differ from the previous response which included this particular etag. If they mismatch,
-     * search will return the rest of SearchResponse along with a new etag.
-     */
-    etag?: string;
-    /**
-     * An abort signal to pass down to the underlying request.
-     *
-     * @remarks
-     *
-     * Not all reader implementations may take this field into account.
-     */
-    signal?: AbortSignal;
+type CacheServiceSetOptions = {
     /**
-     * An optional token to use for authentication when reading the resources.
-     *
-     * @remarks
-     *
-     * By default all URL Readers will use the integrations config which is supplied
-     * when creating the Readers. Sometimes it might be desireable to use the already
-     * created URLReaders but with a different token, maybe that's supplied by the user
-     * at runtime.
+     * Optional TTL (in milliseconds if given as a number). Defaults to the TTL provided when the client
+     * was set up (or no TTL if none are provided).
      */
-    token?: string;
+    ttl?: number | HumanDuration;
 };
 /**
- * The output of a search operation.
+ * Options passed to {@link CacheService.withOptions}.
  *
  * @public
  */
-type UrlReaderServiceSearchResponse = {
-    /**
-     * The files that matched the search query.
-     */
-    files: UrlReaderServiceSearchResponseFile[];
+type CacheServiceOptions = {
     /**
-     * A unique identifier of the current remote tree, usually the commit SHA or etag from the target.
+     * An optional default TTL (in milliseconds if given as a number) to be set when getting a client
+     * instance. If not provided, data will persist indefinitely by default (or
+     * can be configured per entry at set-time).
      */
-    etag: string;
+    defaultTtl?: number | HumanDuration;
 };
 /**
- * Represents a single file in a search response.
+ * A pre-configured, storage agnostic cache service suitable for use by
+ * Backstage plugins.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/cache | service documentation} for more details.
  *
  * @public
  */
-type UrlReaderServiceSearchResponseFile = {
+interface CacheService {
     /**
-     * The full URL to the file.
+     * Reads data from a cache store for the given key. If no data was found,
+     * returns undefined.
      */
-    url: string;
+    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
     /**
-     * The binary contents of the file.
+     * Writes the given data to a cache store, associated with the given key. An
+     * optional TTL may also be provided, otherwise it defaults to the TTL that
+     * was provided when the client was instantiated.
      */
-    content(): Promise<Buffer>;
+    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
     /**
-     * The last modified timestamp of the data.
+     * Removes the given key from the cache store.
      */
-    lastModifiedAt?: Date;
-};
+    delete(key: string): Promise<void>;
+    /**
+     * Creates a new {@link CacheService} instance with the given options.
+     */
+    withOptions(options: CacheServiceOptions): CacheService;
+}
 
 /**
- * A function that can be called as a scheduled task.
+ * Manages access to databases that plugins get.
  *
- * It may optionally accept an abort signal argument. When the signal triggers,
- * processing should abort and return as quickly as possible.
+ * See the {@link https://backstage.io/docs/backend-system/core-services/database | service documentation} for more details.
  *
  * @public
  */
-type SchedulerServiceTaskFunction = ((abortSignal: AbortSignal) => void | Promise<void>) | (() => void | Promise<void>);
+interface DatabaseService {
+    /**
+     * getClient provides backend plugins database connections for itself.
+     *
+     * The purpose of this method is to allow plugins to get isolated data
+     * stores so that plugins are discouraged from database integration.
+     */
+    getClient(): Promise<Knex>;
+    /**
+     * This property is used to control the behavior of database migrations.
+     */
+    migrations?: {
+        /**
+         * skip database migrations. Useful if connecting to a read-only database.
+         *
+         * @defaultValue false
+         */
+        skip?: boolean;
+    };
+}
+
 /**
- * A semi-opaque type to describe an actively scheduled task.
+ * The DiscoveryService is used to provide a mechanism for backend
+ * plugins to discover the endpoints for itself or other backend plugins.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/discovery | service documentation} for more details.
+ *
+ * @remarks
+ *
+ * The purpose of the discovery API is to allow for many different deployment
+ * setups and routing methods through a central configuration, instead
+ * of letting each individual plugin manage that configuration.
+ *
+ * Implementations of the discovery API can be as simple as a URL pattern
+ * using the pluginId, but could also have overrides for individual plugins,
+ * or query a separate discovery service.
  *
  * @public
  */
-type SchedulerServiceTaskDescriptor = {
-    /**
-     * The unique identifier of the task.
-     */
-    id: string;
+interface DiscoveryService {
     /**
-     * The scope of the task.
+     * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
+     *
+     * @remarks
+     *
+     * The returned URL should point to an internal endpoint for the plugin, with
+     * the shortest route possible. The URL should be used for service-to-service
+     * communication within a Backstage backend deployment.
+     *
+     * This method must always be called just before making each request, as opposed to
+     * fetching the URL once when constructing an API client. That is to ensure that more
+     * flexible routing patterns can be supported where a different result might be returned each time.
+     *
+     * For example, asking for the URL for `catalog` may return something
+     * like `http://10.1.2.3/api/catalog`
      */
-    scope: 'global' | 'local';
+    getBaseUrl(pluginId: string): Promise<string>;
     /**
-     * The settings that control the task flow. This is a semi-opaque structure
-     * that is mainly there for debugging purposes. Do not make any assumptions
-     * about the contents of this field.
+     * Returns the external HTTP base backend URL for a given plugin, without a trailing slash.
+     *
+     * @remarks
+     *
+     * The returned URL should point to an external endpoint for the plugin, such that
+     * it is reachable from the Backstage frontend and other external services. The returned
+     * URL should be usable for example as a callback / webhook URL.
+     *
+     * The returned URL should be stable and in general not change unless other static
+     * or external configuration is changed. Changes should not come as a surprise
+     * to an operator of the Backstage backend.
+     *
+     * For example, asking for the URL for `catalog` may return something
+     * like `https://backstage.example.com/api/catalog`
      */
-    settings: {
-        version: number;
-    } & JsonObject;
-};
+    getExternalBaseUrl(pluginId: string): Promise<string>;
+}
+
 /**
- * Options that control the scheduling of a task.
+ * Provides handling of credentials in an ongoing request.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-auth | service documentation} for more details.
  *
  * @public
  */
-interface SchedulerServiceTaskScheduleDefinition {
+interface HttpAuthService {
     /**
-     * How often you want the task to run. The system does its best to avoid
-     * overlapping invocations.
+     * Extracts the caller's credentials from a request.
      *
      * @remarks
      *
-     * This is the best effort value; under some circumstances there can be
-     * deviations. For example, if the task runtime is longer than the frequency
-     * and the timeout has not been given or not been exceeded yet, the next
-     * invocation of this task will be delayed until after the previous one
-     * finishes.
-     *
-     * This is a required field.
-     */
-    frequency: {
-        /**
-         * A crontab style string.
-         *
-         * @remarks
-         *
-         * Overview:
-         *
-         * ```
-         *   ┌────────────── second (optional)
-         *   │ ┌──────────── minute
-         *   │ │ ┌────────── hour
-         *   │ │ │ ┌──────── day of month
-         *   │ │ │ │ ┌────── month
-         *   │ │ │ │ │ ┌──── day of week
-         *   │ │ │ │ │ │
-         *   │ │ │ │ │ │
-         *   * * * * * *
-         * ```
-         */
-        cron: string;
-    } | Duration | HumanDuration | {
-        trigger: 'manual';
-    };
-    /**
-     * The maximum amount of time that a single task invocation can take, before
-     * it's considered timed out and gets "released" such that a new invocation
-     * is permitted to take place (possibly, then, on a different worker).
-     */
-    timeout: Duration | HumanDuration;
-    /**
-     * The amount of time that should pass before the first invocation happens.
-     *
-     * @remarks
+     * The credentials have been validated before returning, and are guaranteed to
+     * adhere to whatever policies have been added to this route using
+     * {@link HttpRouterService.addAuthPolicy}, if any.
      *
-     * This can be useful in cold start scenarios to stagger or delay some heavy
-     * compute jobs. If no value is given for this field then the first invocation
-     * will happen as soon as possible according to the cadence.
+     * Further restrictions can be imposed by passing in options that control the
+     * allowed types of credential.
      *
-     * NOTE: This is a per-worker delay. If you have a cluster of workers all
-     * collaborating on a task that has its `scope` field set to `'global'`, then
-     * you may still see the task being processed by other long-lived workers,
-     * while any given single worker is in its initial sleep delay time e.g. after
-     * a deployment. Therefore, this parameter is not useful for "globally" pausing
-     * work; its main intended use is for individual machines to get a chance to
-     * reach some equilibrium at startup before triggering heavy batch workloads.
+     * You can narrow the returned credentials object to specific principal types
+     * using {@link AuthService.isPrincipal}.
      */
-    initialDelay?: Duration | HumanDuration;
+    credentials<TAllowed extends keyof BackstagePrincipalTypes = 'unknown'>(
     /**
-     * Sets the scope of concurrency control / locking to apply for invocations of
-     * this task.
-     *
-     * @remarks
-     *
-     * When the scope is set to the default value `'global'`, the scheduler will
-     * attempt to ensure that only one worker machine runs the task at a time,
-     * according to the given cadence. This means that as the number of worker
-     * hosts increases, the invocation frequency of this task will not go up.
-     * Instead, the load is spread randomly across hosts. This setting is useful
-     * for tasks that access shared resources, for example catalog ingestion tasks
-     * where you do not want many machines to repeatedly import the same data and
-     * trample over each other.
-     *
-     * When the scope is set to `'local'`, there is no concurrency control across
-     * hosts. Each host runs the task according to the given cadence similarly to
-     * `setInterval`, but the runtime ensures that there are no overlapping runs.
-     *
-     * @defaultValue 'global'
+     * An Express request object.
      */
-    scope?: 'global' | 'local';
-}
-/**
- * Config options for {@link SchedulerServiceTaskScheduleDefinition}
- * that control the scheduling of a task.
- *
- * @public
- */
-interface SchedulerServiceTaskScheduleDefinitionConfig {
+    req: Request<any, any, any, any, any>, 
     /**
-     * How often you want the task to run. The system does its best to avoid
-     * overlapping invocations.
-     *
-     * @remarks
-     *
-     * This is the best effort value; under some circumstances there can be
-     * deviations. For example, if the task runtime is longer than the frequency
-     * and the timeout has not been given or not been exceeded yet, the next
-     * invocation of this task will be delayed until after the previous one
-     * finishes.
-     *
-     * This is a required field.
+     * Optional further restrictions.
      */
-    frequency: {
+    options?: {
         /**
-         * A crontab style string.
+         * If specified, allow only principals of the given type(s).
          *
-         * @remarks
+         * If the incoming credentials were not of a type that matched this
+         * restriction, a {@link @backstage/errors#NotAllowedError} is thrown.
          *
-         * Overview:
+         * The default is to allow user and service principals.
+         */
+        allow?: Array<TAllowed>;
+        /**
+         * If set to true, allow limited access tokens (such as cookies).
          *
-         * ```
-         *   ┌────────────── second (optional)
-         *   │ ┌──────────── minute
-         *   │ │ ┌────────── hour
-         *   │ │ │ ┌──────── day of month
-         *   │ │ │ │ ┌────── month
-         *   │ │ │ │ │ ┌──── day of week
-         *   │ │ │ │ │ │
-         *   │ │ │ │ │ │
-         *   * * * * * *
-         * ```
+         * If this flag is not set, or is set to false, calls with limited access
+         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+         * thrown.
          */
-        cron: string;
-    } | string | HumanDuration
-    /**
-     * This task will only run when manually triggered with the `triggerTask` method; no automatic
-     * scheduling. This is useful for locking of global tasks that should not be run concurrently.
-     */
-     | {
-        trigger: 'manual';
-    };
-    /**
-     * The maximum amount of time that a single task invocation can take, before
-     * it's considered timed out and gets "released" such that a new invocation
-     * is permitted to take place (possibly, then, on a different worker).
-     */
-    timeout: string | HumanDuration;
-    /**
-     * The amount of time that should pass before the first invocation happens.
-     *
-     * @remarks
-     *
-     * This can be useful in cold start scenarios to stagger or delay some heavy
-     * compute jobs. If no value is given for this field then the first invocation
-     * will happen as soon as possible according to the cadence.
-     *
-     * NOTE: This is a per-worker delay. If you have a cluster of workers all
-     * collaborating on a task that has its `scope` field set to `'global'`, then
-     * you may still see the task being processed by other long-lived workers,
-     * while any given single worker is in its initial sleep delay time e.g. after
-     * a deployment. Therefore, this parameter is not useful for "globally" pausing
-     * work; its main intended use is for individual machines to get a chance to
-     * reach some equilibrium at startup before triggering heavy batch workloads.
-     */
-    initialDelay?: string | HumanDuration;
+        allowLimitedAccess?: boolean;
+    }): Promise<BackstageCredentials<BackstagePrincipalTypes[TAllowed]>>;
     /**
-     * Sets the scope of concurrency control / locking to apply for invocations of
-     * this task.
-     *
-     * @remarks
-     *
-     * When the scope is set to the default value `'global'`, the scheduler will
-     * attempt to ensure that only one worker machine runs the task at a time,
-     * according to the given cadence. This means that as the number of worker
-     * hosts increases, the invocation frequency of this task will not go up.
-     * Instead, the load is spread randomly across hosts. This setting is useful
-     * for tasks that access shared resources, for example catalog ingestion tasks
-     * where you do not want many machines to repeatedly import the same data and
-     * trample over each other.
-     *
-     * When the scope is set to `'local'`, there is no concurrency control across
-     * hosts. Each host runs the task according to the given cadence similarly to
-     * `setInterval`, but the runtime ensures that there are no overlapping runs.
+     * Issues a limited access token as a cookie on the given response object.
+     * This is only possible for requests that were originally made with user
+     * credentials (such as a Backstage token).
      *
-     * @defaultValue 'global'
-     */
-    scope?: 'global' | 'local';
-}
-/**
- * Options that apply to the invocation of a given task.
- *
- * @public
- */
-interface SchedulerServiceTaskInvocationDefinition {
-    /**
-     * A unique ID (within the scope of the plugin) for the task.
+     * This must be called before sending any payload data.
      */
-    id: string;
+    issueUserCookie(
     /**
-     * The actual task function to be invoked regularly.
+     * An Express response object.
      */
-    fn: SchedulerServiceTaskFunction;
+    res: Response, 
     /**
-     * An abort signal that, when triggered, will stop the recurring execution of
-     * the task.
+     * Optional further settings.
      */
-    signal?: AbortSignal;
+    options?: {
+        /**
+         * Issue the cookie for this specific credential. Must be a "user" type
+         * principal, or a "none" type (which leads to deleting the cookie).
+         *
+         * @remarks
+         *
+         * Normally you do not have to specify this option, because the default
+         * behavior is to extract the credentials from the request that
+         * corresponded to the given respnse.
+         */
+        credentials?: BackstageCredentials;
+    }): Promise<{
+        expiresAt: Date;
+    }>;
 }
+
 /**
- * A previously prepared task schedule, ready to be invoked.
+ * Options for {@link HttpRouterService.addAuthPolicy}.
  *
  * @public
  */
-interface SchedulerServiceTaskRunner {
-    /**
-     * Takes the schedule and executes an actual task using it.
-     *
-     * @param task - The actual runtime properties of the task
-     */
-    run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;
+interface HttpRouterServiceAuthPolicy {
+    path: string;
+    allow: 'unauthenticated' | 'user-cookie';
 }
 /**
- * Deals with the scheduling of distributed tasks, for a given plugin.
+ * Allows plugins to register HTTP routes.
  *
- * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-router | service documentation} for more details.
  *
  * @public
  */
-interface SchedulerService {
-    /**
-     * Manually triggers a task by ID.
-     *
-     * If the task doesn't exist, a NotFoundError is thrown. If the task is
-     * currently running, a ConflictError is thrown.
-     *
-     * @param id - The task ID
-     */
-    triggerTask(id: string): Promise<void>;
+interface HttpRouterService {
     /**
-     * Schedules a task function for recurring runs.
-     *
-     * @remarks
-     *
-     * The `scope` task field controls whether to use coordinated exclusive
-     * invocation across workers, or to just coordinate within the current worker.
-     *
-     * This convenience method performs both the scheduling and invocation in one
-     * go.
-     *
-     * @param task - The task definition
+     * Registers an Express request handler under the plugin's base router. This
+     * typically makes its base path `/api/<plugin-id>`.
      */
-    scheduleTask(task: SchedulerServiceTaskScheduleDefinition & SchedulerServiceTaskInvocationDefinition): Promise<void>;
+    use(handler: Handler): void;
     /**
-     * Creates a scheduled but dormant recurring task, ready to be launched at a
-     * later time.
+     * Adds an auth policy to the router. This is used to allow unauthenticated or
+     * cookie based access to parts of a plugin's API.
      *
      * @remarks
      *
-     * This method is useful for pre-creating a schedule in outer code to be
-     * passed into an inner implementation, such that the outer code controls
-     * scheduling while inner code controls implementation.
-     *
-     * @param schedule - The task schedule
-     */
-    createScheduledTaskRunner(schedule: SchedulerServiceTaskScheduleDefinition): SchedulerServiceTaskRunner;
-    /**
-     * Returns all scheduled tasks registered to this scheduler.
+     * The paths given follow the same pattern as the routers given to the `use`
+     * method, that is, they are relative to the plugin's base URL, and can
+     * contain placeholders.
      *
-     * @remarks
+     * @example
      *
-     * This method is useful for triggering tasks manually using the triggerTask
-     * functionality. Note that the returned tasks contain only tasks that have
-     * been initialized in this instance of the scheduler.
+     * ```ts
+     * http.addAuthPolicy({
+     *   path: '/static/:id',
+     *   allow: 'user-cookie',
+     * });
+     * ```
      *
-     * @returns Scheduled tasks
+     * This allows limited access tokens via cookies on the
+     * `/api/<plugin-id>/static/*` paths, but not unauthenticated access.
      */
-    getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;
+    addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
 }
-/**
- * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects
- * the config not to be the root config, but the config for the definition.
- *
- * @param config - config for a TaskScheduleDefinition.
- * @public
- */
-declare function readSchedulerServiceTaskScheduleDefinitionFromConfig(config: Config): SchedulerServiceTaskScheduleDefinition;
 
 /**
  * A service that provides a logging facility.
@@ -658,16 +552,6 @@ interface LoggerService {
     child(meta: JsonObject): LoggerService;
 }
 
-/**
- * Root-level logging.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/root-logger | service documentation} for more details.
- *
- * @public
- */
-interface RootLoggerService extends LoggerService {
-}
-
 /**
  * @public
  */
@@ -719,29 +603,148 @@ interface LifecycleService {
 }
 
 /**
- * Registration of backend startup and shutdown lifecycle hooks.
+ * Options for {@link PermissionsService} requests.
  *
- * See the {@link https://backstage.io/docs/backend-system/core-services/root-lifecycle | service documentation} for more details.
+ * @public
+ */
+interface PermissionsServiceRequestOptions extends EvaluatorRequestOptions {
+    credentials: BackstageCredentials;
+}
+/**
+ * Permission system integration for authorization of user/service actions.
+ *
+ * See the {@link https://backstage.io/docs/permissions/overview | permissions documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/permissions | service documentation}
+ * for more details.
  *
  * @public
  */
-interface RootLifecycleService extends LifecycleService {
-    addBeforeShutdownHook(hook: () => void | Promise<void>): void;
+interface PermissionsService extends PermissionEvaluator {
+    /**
+     * Evaluates
+     * {@link @backstage/plugin-permission-common#Permission | Permissions} and
+     * returns definitive decisions.
+     *
+     * @remarks
+     *
+     * The returned array has the same number of items, in the same order, as the
+     * given requests.
+     */
+    authorize(requests: AuthorizePermissionRequest[], options: PermissionsServiceRequestOptions): Promise<AuthorizePermissionResponse[]>;
+    /**
+     * Evaluates {@link @backstage/plugin-permission-common#ResourcePermission | ResourcePermissions} and returns both definitive and
+     * conditional decisions, depending on the configured
+     * {@link @backstage/plugin-permission-node#PermissionPolicy}.
+     *
+     * @remarks
+     *
+     * This method is useful when the
+     * caller needs more control over the processing of conditional decisions. For example, a plugin
+     * backend may want to use {@link @backstage/plugin-permission-common#PermissionCriteria | conditions} in a database query instead of
+     * evaluating each resource in memory.
+     *
+     * The returned array has the same number of items, in the same order, as the
+     * given requests.
+     */
+    authorizeConditional(requests: QueryPermissionRequest[], options: PermissionsServiceRequestOptions): Promise<QueryPermissionResponse[]>;
 }
 
 /**
- * HTTP route registration for root services.
+ * Prevent use of type parameter from contributing to type inference.
  *
- * See the {@link https://backstage.io/docs/backend-system/core-services/root-http-router | service documentation} for more details.
+ * https://github.com/Microsoft/TypeScript/issues/14829#issuecomment-980401795
+ * @ignore
+ */
+type NoInfer<T> = T extends infer S ? S : never;
+/**
+ * Options for adding a resource type to the permission system.
  *
  * @public
  */
-interface RootHttpRouterService {
+type PermissionsRegistryServiceAddResourceTypeOptions<TResourceType extends string, TResource> = {
     /**
-     * Registers a handler at the root of the backend router.
-     * The path is required and may not be empty.
+     * The identifier for the resource type.
      */
-    use(path: string, handler: Handler): void;
+    resourceType: TResourceType;
+    /**
+     * Permissions that are available for this resource type.
+     */
+    permissions?: Array<Permission>;
+    /**
+     * Permission rules that are available for this resource type.
+     */
+    rules: PermissionRule<TResource, any, NoInfer<TResourceType>>[];
+    /**
+     * The function used to load associated resources based in the provided
+     * references.
+     *
+     * @remarks
+     *
+     * If this function is not provided the permission system will not be able to
+     * resolve conditional decisions except when requesting resources directly
+     * from the plugin.
+     */
+    getResources?(resourceRefs: string[]): Promise<Array<TResource | undefined>>;
+};
+/**
+ * Permission system integration for registering resources and permissions.
+ *
+ * See the {@link https://backstage.io/docs/permissions/overview | permissions documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/permission-integrations | service documentation}
+ * for more details.
+ *
+ * @public
+ */
+interface PermissionsRegistryService {
+    /**
+     * Add permissions for this plugin to the permission system.
+     */
+    addPermissions(permissions: Permission[]): void;
+    /**
+     * Adds a set of permission rules to the permission system for a resource type
+     * that is owned by this plugin.
+     *
+     * @remarks
+     *
+     * Rules should be created using corresponding `create*PermissionRule`
+     * functions exported by plugins, who in turn are created with
+     * `makeCreatePermissionRule`.
+     *
+     * Rules can be added either directly by the plugin itself or through a plugin
+     * module.
+     */
+    addPermissionRules(rules: PermissionRule<any, any, string>[]): void;
+    /**
+     * Add a new resource type that is owned by this plugin to the permission
+     * system.
+     *
+     * @remarks
+     *
+     * To make this concrete, we can use the Backstage software catalog as an
+     * example. The catalog has conditional rules around access to specific
+     * _entities_ in the catalog. The _type_ of resource is captured here as
+     * `resourceType`, a string identifier (`catalog-entity` in this example) that
+     * can be provided with permission definitions. This is merely a _type_ to
+     * verify that conditions in an authorization policy are constructed
+     * correctly, not a reference to a specific resource.
+     *
+     * The `rules` parameter is an array of
+     * {@link @backstage/plugin-permission-node#PermissionRule}s that introduce
+     * conditional filtering logic for resources; for the catalog, these are
+     * things like `isEntityOwner` or `hasAnnotation`. Rules describe how to
+     * filter a list of resources, and the `conditions` returned allow these rules
+     * to be applied with specific parameters (such as 'group:default/team-a', or
+     * 'backstage.io/edit-url').
+     *
+     * The `getResources` argument should load resources based on a reference
+     * identifier. For the catalog, this is an
+     * [entity reference](https://backstage.io/docs/features/software-catalog/references#string-references).
+     * For other plugins, this can be any serialized format. This is used to add a
+     * permissions registry API via the HTTP router service. This API will be
+     * called by the `permission-backend` when authorization conditions relating
+     * to this plugin need to be evaluated.
+     */
+    addResourceType<const TResourceType extends string, TResource>(options: PermissionsRegistryServiceAddResourceTypeOptions<TResourceType, TResource>): void;
 }
 
 /**
@@ -759,563 +762,707 @@ interface PluginMetadataService {
 }
 
 /**
- * Represents a user principal (for example when a user Backstage token issued
- * by the auth backend was given to a request).
+ * Provides access to static configuration.
  *
- * @remarks
+ * See the {@link https://backstage.io/docs/conf/ | configuration documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/root-config | service documentation}
+ * for more details.
  *
- * Additional information about the user can be fetched using the
- * {@link UserInfoService}.
+ * @public
+ */
+interface RootConfigService extends Config {
+}
+
+/**
+ * @public
+ */
+interface RootHealthService {
+    /**
+     * Get the liveness status of the backend.
+     */
+    getLiveness(): Promise<{
+        status: number;
+        payload?: JsonValue;
+    }>;
+    /**
+     * Get the readiness status of the backend.
+     */
+    getReadiness(): Promise<{
+        status: number;
+        payload?: JsonValue;
+    }>;
+}
+
+/**
+ * HTTP route registration for root services.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-http-router | service documentation} for more details.
  *
  * @public
  */
-type BackstageUserPrincipal = {
-    type: 'user';
+interface RootHttpRouterService {
     /**
-     * The entity ref of the user entity that this principal represents.
+     * Registers a handler at the root of the backend router.
+     * The path is required and may not be empty.
      */
-    userEntityRef: string;
-};
+    use(path: string, handler: Handler): void;
+}
+
 /**
- * Represents a principal that is not authenticated (for example when no token
- * at all was given to a request).
+ * Registration of backend startup and shutdown lifecycle hooks.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-lifecycle | service documentation} for more details.
  *
  * @public
  */
-type BackstageNonePrincipal = {
-    type: 'none';
+interface RootLifecycleService extends LifecycleService {
+    addBeforeShutdownHook(hook: () => void | Promise<void>): void;
+}
+
+/**
+ * Root-level logging.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-logger | service documentation} for more details.
+ *
+ * @public
+ */
+interface RootLoggerService extends LoggerService {
+}
+
+/**
+ * A function that can be called as a scheduled task.
+ *
+ * It may optionally accept an abort signal argument. When the signal triggers,
+ * processing should abort and return as quickly as possible.
+ *
+ * @public
+ */
+type SchedulerServiceTaskFunction = ((abortSignal: AbortSignal) => void | Promise<void>) | (() => void | Promise<void>);
+/**
+ * A semi-opaque type to describe an actively scheduled task.
+ *
+ * @public
+ */
+type SchedulerServiceTaskDescriptor = {
+    /**
+     * The unique identifier of the task.
+     */
+    id: string;
+    /**
+     * The scope of the task.
+     */
+    scope: 'global' | 'local';
+    /**
+     * The settings that control the task flow. This is a semi-opaque structure
+     * that is mainly there for debugging purposes. Do not make any assumptions
+     * about the contents of this field.
+     */
+    settings: {
+        version: number;
+    } & JsonObject;
 };
 /**
- * Represents a service principal (for example when an external access method
- * token was given to a request, or the caller was a Backstage backend plugin).
+ * Options that control the scheduling of a task.
+ *
  * @public
  */
-type BackstageServicePrincipal = {
-    type: 'service';
+interface SchedulerServiceTaskScheduleDefinition {
     /**
-     * A string that represents the service.
+     * How often you want the task to run. The system does its best to avoid
+     * overlapping invocations.
      *
      * @remarks
      *
-     * This string is only informational, has no well defined semantics, and
-     * should never be used to drive actual logic in code.
+     * This is the best effort value; under some circumstances there can be
+     * deviations. For example, if the task runtime is longer than the frequency
+     * and the timeout has not been given or not been exceeded yet, the next
+     * invocation of this task will be delayed until after the previous one
+     * finishes.
+     *
+     * This is a required field.
+     */
+    frequency: {
+        /**
+         * A crontab style string.
+         *
+         * @remarks
+         *
+         * Overview:
+         *
+         * ```
+         *   ┌────────────── second (optional)
+         *   │ ┌──────────── minute
+         *   │ │ ┌────────── hour
+         *   │ │ │ ┌──────── day of month
+         *   │ │ │ │ ┌────── month
+         *   │ │ │ │ │ ┌──── day of week
+         *   │ │ │ │ │ │
+         *   │ │ │ │ │ │
+         *   * * * * * *
+         * ```
+         */
+        cron: string;
+    } | Duration | HumanDuration | {
+        trigger: 'manual';
+    };
+    /**
+     * The maximum amount of time that a single task invocation can take, before
+     * it's considered timed out and gets "released" such that a new invocation
+     * is permitted to take place (possibly, then, on a different worker).
      */
-    subject: string;
+    timeout: Duration | HumanDuration;
     /**
-     * The access restrictions that apply to this principal.
+     * The amount of time that should pass before the first invocation happens.
      *
      * @remarks
      *
-     * If no access restrictions are provided the principal is assumed to have
-     * unlimited access, at a framework level. The permissions system and
-     * individual plugins may or may not still apply additional access controls on
-     * top of this.
+     * This can be useful in cold start scenarios to stagger or delay some heavy
+     * compute jobs. If no value is given for this field then the first invocation
+     * will happen as soon as possible according to the cadence.
+     *
+     * NOTE: This is a per-worker delay. If you have a cluster of workers all
+     * collaborating on a task that has its `scope` field set to `'global'`, then
+     * you may still see the task being processed by other long-lived workers,
+     * while any given single worker is in its initial sleep delay time e.g. after
+     * a deployment. Therefore, this parameter is not useful for "globally" pausing
+     * work; its main intended use is for individual machines to get a chance to
+     * reach some equilibrium at startup before triggering heavy batch workloads.
      */
-    accessRestrictions?: BackstagePrincipalAccessRestrictions;
-};
-/**
- * The access restrictions that apply to a given principal.
- *
- * @public
- */
-type BackstagePrincipalAccessRestrictions = {
+    initialDelay?: Duration | HumanDuration;
     /**
-     * If given, the principal is limited to only performing actions with these
-     * named permissions.
+     * Sets the scope of concurrency control / locking to apply for invocations of
+     * this task.
      *
-     * Note that this only applies where permissions checks are enabled in the
-     * first place. Endpoints that are not protected by the permissions system at
-     * all, are not affected by this setting.
+     * @remarks
      *
-     * This array always has at least one element, or is missing entirely.
-     */
-    permissionNames?: string[];
-    /**
-     * If given, the principal is limited to only performing actions whose
-     * permissions have these attributes.
+     * When the scope is set to the default value `'global'`, the scheduler will
+     * attempt to ensure that only one worker machine runs the task at a time,
+     * according to the given cadence. This means that as the number of worker
+     * hosts increases, the invocation frequency of this task will not go up.
+     * Instead, the load is spread randomly across hosts. This setting is useful
+     * for tasks that access shared resources, for example catalog ingestion tasks
+     * where you do not want many machines to repeatedly import the same data and
+     * trample over each other.
      *
-     * Note that this only applies where permissions checks are enabled in the
-     * first place. Endpoints that are not protected by the permissions system at
-     * all, are not affected by this setting.
+     * When the scope is set to `'local'`, there is no concurrency control across
+     * hosts. Each host runs the task according to the given cadence similarly to
+     * `setInterval`, but the runtime ensures that there are no overlapping runs.
      *
-     * This object always has at least one key, or is missing entirely.
+     * @defaultValue 'global'
      */
-    permissionAttributes?: {
-        /**
-         * Match any of these action values. This array always has at least one
-         * element, or is missing entirely.
-         */
-        action?: Array<Required<PermissionAttributes>['action']>;
-    };
-};
+    scope?: 'global' | 'local';
+}
 /**
- * An opaque representation of credentials, for example as passed in a
- * request-response flow.
+ * Config options for {@link SchedulerServiceTaskScheduleDefinition}
+ * that control the scheduling of a task.
  *
  * @public
  */
-type BackstageCredentials<TPrincipal = unknown> = {
-    $$type: '@backstage/BackstageCredentials';
-    /**
-     * If the credentials have a limited lifetime, this is the time at which they
-     * expire and may no longer be accepted by a receiver.
-     */
-    expiresAt?: Date;
+interface SchedulerServiceTaskScheduleDefinitionConfig {
     /**
-     * The principal (originator) of the request.
+     * How often you want the task to run. The system does its best to avoid
+     * overlapping invocations.
      *
      * @remarks
      *
-     * This is semantically the originator of a request chain, and may or may not
-     * represent the immediate caller of your service. For example, in
-     * on-behalf-of scenarios, the immediate caller may be an intermediary backend
-     * service, but the principal may still be a user that was the original
-     * caller.
-     */
-    principal: TPrincipal;
-};
-/**
- * The types of principal that can be represented in a
- * {@link BackstageCredentials} object.
- *
- * @public
- */
-type BackstagePrincipalTypes = {
-    user: BackstageUserPrincipal;
-    service: BackstageServicePrincipal;
-    none: BackstageNonePrincipal;
-    unknown: unknown;
-};
-/**
- * Provides token authentication and credentials management.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/auth | service documentation} for more details.
- *
- * @public
- */
-interface AuthService {
-    /**
-     * Verifies a token and returns the associated credentials.
+     * This is the best effort value; under some circumstances there can be
+     * deviations. For example, if the task runtime is longer than the frequency
+     * and the timeout has not been given or not been exceeded yet, the next
+     * invocation of this task will be delayed until after the previous one
+     * finishes.
+     *
+     * This is a required field.
      */
-    authenticate(token: string, options?: {
+    frequency: {
         /**
-         * If set to true, allow limited access tokens (such as cookies).
+         * A crontab style string.
          *
-         * If this flag is not set, or is set to false, calls with limited access
-         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
-         * thrown.
+         * @remarks
+         *
+         * Overview:
+         *
+         * ```
+         *   ┌────────────── second (optional)
+         *   │ ┌──────────── minute
+         *   │ │ ┌────────── hour
+         *   │ │ │ ┌──────── day of month
+         *   │ │ │ │ ┌────── month
+         *   │ │ │ │ │ ┌──── day of week
+         *   │ │ │ │ │ │
+         *   │ │ │ │ │ │
+         *   * * * * * *
+         * ```
          */
-        allowLimitedAccess?: boolean;
-    }): Promise<BackstageCredentials>;
+        cron: string;
+    } | string | HumanDuration
     /**
-     * Checks if the given credentials are of the given type, and narrows the
-     * TypeScript type accordingly if there's a match.
+     * This task will only run when manually triggered with the `triggerTask` method; no automatic
+     * scheduling. This is useful for locking of global tasks that should not be run concurrently.
      */
-    isPrincipal<TType extends keyof BackstagePrincipalTypes>(credentials: BackstageCredentials, type: TType): credentials is BackstageCredentials<BackstagePrincipalTypes[TType]>;
+     | {
+        trigger: 'manual';
+    };
     /**
-     * Create a credentials object that represents an unauthenticated caller.
+     * The maximum amount of time that a single task invocation can take, before
+     * it's considered timed out and gets "released" such that a new invocation
+     * is permitted to take place (possibly, then, on a different worker).
      */
-    getNoneCredentials(): Promise<BackstageCredentials<BackstageNonePrincipal>>;
+    timeout: string | HumanDuration;
     /**
-     * Create a credentials object that represents the current service itself.
+     * The amount of time that should pass before the first invocation happens.
+     *
+     * @remarks
+     *
+     * This can be useful in cold start scenarios to stagger or delay some heavy
+     * compute jobs. If no value is given for this field then the first invocation
+     * will happen as soon as possible according to the cadence.
+     *
+     * NOTE: This is a per-worker delay. If you have a cluster of workers all
+     * collaborating on a task that has its `scope` field set to `'global'`, then
+     * you may still see the task being processed by other long-lived workers,
+     * while any given single worker is in its initial sleep delay time e.g. after
+     * a deployment. Therefore, this parameter is not useful for "globally" pausing
+     * work; its main intended use is for individual machines to get a chance to
+     * reach some equilibrium at startup before triggering heavy batch workloads.
      */
-    getOwnServiceCredentials(): Promise<BackstageCredentials<BackstageServicePrincipal>>;
+    initialDelay?: string | HumanDuration;
     /**
-     * Issue a token that can be used for authenticating calls towards other
-     * backend plugins.
+     * Sets the scope of concurrency control / locking to apply for invocations of
+     * this task.
      *
      * @remarks
      *
-     * This method should be called before each request. Do not hold on to the
-     * issued token and reuse it for future calls.
+     * When the scope is set to the default value `'global'`, the scheduler will
+     * attempt to ensure that only one worker machine runs the task at a time,
+     * according to the given cadence. This means that as the number of worker
+     * hosts increases, the invocation frequency of this task will not go up.
+     * Instead, the load is spread randomly across hosts. This setting is useful
+     * for tasks that access shared resources, for example catalog ingestion tasks
+     * where you do not want many machines to repeatedly import the same data and
+     * trample over each other.
+     *
+     * When the scope is set to `'local'`, there is no concurrency control across
+     * hosts. Each host runs the task according to the given cadence similarly to
+     * `setInterval`, but the runtime ensures that there are no overlapping runs.
+     *
+     * @defaultValue 'global'
      */
-    getPluginRequestToken(options: {
-        /**
-         * The credentials of the originator of the request.
-         *
-         * @remarks
-         *
-         * This is most commonly the result of
-         * {@link AuthService.getOwnServiceCredentials} when the current service is
-         * the originator, or the output of {@link HttpAuthService.credentials} when
-         * performing requests on behalf of an incoming request identity.
-         */
-        onBehalfOf: BackstageCredentials;
-        /**
-         * The ID of the plugin that the request is being made to.
-         */
-        targetPluginId: string;
-    }): Promise<{
-        token: string;
-    }>;
+    scope?: 'global' | 'local';
+}
+/**
+ * Options that apply to the invocation of a given task.
+ *
+ * @public
+ */
+interface SchedulerServiceTaskInvocationDefinition {
     /**
-     * Issue a limited user token that can be used e.g. in cookie flows.
+     * A unique ID (within the scope of the plugin) for the task.
      */
-    getLimitedUserToken(
+    id: string;
     /**
-     * The credentials that this token should represent. Must be a user
-     * principal. Commonly the output of {@link HttpAuthService.credentials} is
-     * used as the input.
+     * The actual task function to be invoked regularly.
      */
-    credentials: BackstageCredentials<BackstageUserPrincipal>): Promise<{
-        token: string;
-        expiresAt: Date;
-    }>;
+    fn: SchedulerServiceTaskFunction;
     /**
-     * Retrieve the public keys that have been used to sign tokens that were
-     * issued by this service. This list is periodically pruned from keys that are
-     * significantly past their expiry.
+     * An abort signal that, when triggered, will stop the recurring execution of
+     * the task.
      */
-    listPublicServiceKeys(): Promise<{
-        keys: JsonObject[];
-    }>;
+    signal?: AbortSignal;
 }
-
 /**
- * Options for {@link PermissionsService} requests.
+ * A previously prepared task schedule, ready to be invoked.
  *
  * @public
  */
-interface PermissionsServiceRequestOptions extends EvaluatorRequestOptions {
-    credentials: BackstageCredentials;
+interface SchedulerServiceTaskRunner {
+    /**
+     * Takes the schedule and executes an actual task using it.
+     *
+     * @param task - The actual runtime properties of the task
+     */
+    run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;
 }
 /**
- * Permission system integration for authorization of user/service actions.
+ * Deals with the scheduling of distributed tasks, for a given plugin.
  *
- * See the {@link https://backstage.io/docs/permissions/overview | permissions documentation}
- * and the {@link https://backstage.io/docs/backend-system/core-services/permissions | service documentation}
- * for more details.
+ * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.
  *
  * @public
  */
-interface PermissionsService extends PermissionEvaluator {
+interface SchedulerService {
     /**
-     * Evaluates
-     * {@link @backstage/plugin-permission-common#Permission | Permissions} and
-     * returns definitive decisions.
+     * Manually triggers a task by ID.
+     *
+     * If the task doesn't exist, a NotFoundError is thrown. If the task is
+     * currently running, a ConflictError is thrown.
+     *
+     * @param id - The task ID
+     */
+    triggerTask(id: string): Promise<void>;
+    /**
+     * Schedules a task function for recurring runs.
      *
      * @remarks
      *
-     * The returned array has the same number of items, in the same order, as the
-     * given requests.
+     * The `scope` task field controls whether to use coordinated exclusive
+     * invocation across workers, or to just coordinate within the current worker.
+     *
+     * This convenience method performs both the scheduling and invocation in one
+     * go.
+     *
+     * @param task - The task definition
      */
-    authorize(requests: AuthorizePermissionRequest[], options: PermissionsServiceRequestOptions): Promise<AuthorizePermissionResponse[]>;
+    scheduleTask(task: SchedulerServiceTaskScheduleDefinition & SchedulerServiceTaskInvocationDefinition): Promise<void>;
     /**
-     * Evaluates {@link @backstage/plugin-permission-common#ResourcePermission | ResourcePermissions} and returns both definitive and
-     * conditional decisions, depending on the configured
-     * {@link @backstage/plugin-permission-node#PermissionPolicy}.
+     * Creates a scheduled but dormant recurring task, ready to be launched at a
+     * later time.
      *
      * @remarks
      *
-     * This method is useful when the
-     * caller needs more control over the processing of conditional decisions. For example, a plugin
-     * backend may want to use {@link @backstage/plugin-permission-common#PermissionCriteria | conditions} in a database query instead of
-     * evaluating each resource in memory.
+     * This method is useful for pre-creating a schedule in outer code to be
+     * passed into an inner implementation, such that the outer code controls
+     * scheduling while inner code controls implementation.
      *
-     * The returned array has the same number of items, in the same order, as the
-     * given requests.
+     * @param schedule - The task schedule
      */
-    authorizeConditional(requests: QueryPermissionRequest[], options: PermissionsServiceRequestOptions): Promise<QueryPermissionResponse[]>;
+    createScheduledTaskRunner(schedule: SchedulerServiceTaskScheduleDefinition): SchedulerServiceTaskRunner;
+    /**
+     * Returns all scheduled tasks registered to this scheduler.
+     *
+     * @remarks
+     *
+     * This method is useful for triggering tasks manually using the triggerTask
+     * functionality. Note that the returned tasks contain only tasks that have
+     * been initialized in this instance of the scheduler.
+     *
+     * @returns Scheduled tasks
+     */
+    getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;
 }
-
 /**
- * Options for {@link HttpRouterService.addAuthPolicy}.
+ * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects
+ * the config not to be the root config, but the config for the definition.
  *
+ * @param config - config for a TaskScheduleDefinition.
  * @public
  */
-interface HttpRouterServiceAuthPolicy {
-    path: string;
-    allow: 'unauthenticated' | 'user-cookie';
-}
+declare function readSchedulerServiceTaskScheduleDefinitionFromConfig(config: Config): SchedulerServiceTaskScheduleDefinition;
+
 /**
- * Allows plugins to register HTTP routes.
+ * A generic interface for fetching plain data from URLs.
  *
- * See the {@link https://backstage.io/docs/backend-system/core-services/http-router | service documentation} for more details.
+ * See the {@link https://backstage.io/docs/backend-system/core-services/url-reader | service documentation} for more details.
  *
  * @public
  */
-interface HttpRouterService {
+interface UrlReaderService {
     /**
-     * Registers an Express request handler under the plugin's base router. This
-     * typically makes its base path `/api/<plugin-id>`.
+     * Reads a single file and return its content.
      */
-    use(handler: Handler): void;
+    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
     /**
-     * Adds an auth policy to the router. This is used to allow unauthenticated or
-     * cookie based access to parts of a plugin's API.
-     *
-     * @remarks
-     *
-     * The paths given follow the same pattern as the routers given to the `use`
-     * method, that is, they are relative to the plugin's base URL, and can
-     * contain placeholders.
-     *
-     * @example
-     *
-     * ```ts
-     * http.addAuthPolicy({
-     *   path: '/static/:id',
-     *   allow: 'user-cookie',
-     * });
-     * ```
-     *
-     * This allows limited access tokens via cookies on the
-     * `/api/<plugin-id>/static/*` paths, but not unauthenticated access.
+     * Reads a full or partial file tree.
      */
-    addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
+    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
+    /**
+     * Searches for a file in a tree using a glob pattern.
+     */
+    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
 }
-
 /**
- * Provides handling of credentials in an ongoing request.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/http-auth | service documentation} for more details.
+ * An options object for readUrl operations.
  *
  * @public
  */
-interface HttpAuthService {
+type UrlReaderServiceReadUrlOptions = {
     /**
-     * Extracts the caller's credentials from a request.
+     * An ETag which can be provided to check whether a
+     * {@link UrlReaderService.readUrl} response has changed from a previous execution.
      *
      * @remarks
      *
-     * The credentials have been validated before returning, and are guaranteed to
-     * adhere to whatever policies have been added to this route using
-     * {@link HttpRouterService.addAuthPolicy}, if any.
-     *
-     * Further restrictions can be imposed by passing in options that control the
-     * allowed types of credential.
+     * In the {@link UrlReaderService.readUrl} response, an ETag is returned along with
+     * the data. The ETag is a unique identifier of the data, usually the commit
+     * SHA or ETag from the target.
      *
-     * You can narrow the returned credentials object to specific principal types
-     * using {@link AuthService.isPrincipal}.
+     * When an ETag is given in ReadUrlOptions, {@link UrlReaderService.readUrl} will
+     * first compare the ETag against the ETag of the target. If they match,
+     * {@link UrlReaderService.readUrl} will throw a
+     * {@link @backstage/errors#NotModifiedError} indicating that the response
+     * will not differ from the previous response which included this particular
+     * ETag. If they do not match, {@link UrlReaderService.readUrl} will return the rest
+     * of the response along with a new ETag.
      */
-    credentials<TAllowed extends keyof BackstagePrincipalTypes = 'unknown'>(
+    etag?: string;
     /**
-     * An Express request object.
+     * A date which can be provided to check whether a
+     * {@link UrlReaderService.readUrl} response has changed since the lastModifiedAt.
+     *
+     * @remarks
+     *
+     * In the {@link UrlReaderService.readUrl} response, an lastModifiedAt is returned
+     * along with data. The lastModifiedAt date represents the last time the data
+     * was modified.
+     *
+     * When an lastModifiedAfter is given in ReadUrlOptions, {@link UrlReaderService.readUrl}
+     * will compare the lastModifiedAfter against the lastModifiedAt of the target. If
+     * the data has not been modified since this date, the {@link UrlReaderService.readUrl}
+     * will throw a {@link @backstage/errors#NotModifiedError} indicating that the
+     * response does not contain any new data. If they do not match,
+     * {@link UrlReaderService.readUrl} will return the rest of the response along with new
+     * lastModifiedAt date.
      */
-    req: Request<any, any, any, any, any>, 
+    lastModifiedAfter?: Date;
     /**
-     * Optional further restrictions.
+     * An abort signal to pass down to the underlying request.
+     *
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
      */
-    options?: {
-        /**
-         * If specified, allow only principals of the given type(s).
-         *
-         * If the incoming credentials were not of a type that matched this
-         * restriction, a {@link @backstage/errors#NotAllowedError} is thrown.
-         *
-         * The default is to allow user and service principals.
-         */
-        allow?: Array<TAllowed>;
-        /**
-         * If set to true, allow limited access tokens (such as cookies).
-         *
-         * If this flag is not set, or is set to false, calls with limited access
-         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
-         * thrown.
-         */
-        allowLimitedAccess?: boolean;
-    }): Promise<BackstageCredentials<BackstagePrincipalTypes[TAllowed]>>;
+    signal?: AbortSignal;
     /**
-     * Issues a limited access token as a cookie on the given response object.
-     * This is only possible for requests that were originally made with user
-     * credentials (such as a Backstage token).
+     * An optional token to use for authentication when reading the resources.
      *
-     * This must be called before sending any payload data.
+     * @remarks
+     *
+     * By default all URL Readers will use the integrations config which is supplied
+     * when creating the Readers. Sometimes it might be desireable to use the already
+     * created URLReaders but with a different token, maybe that's supplied by the user
+     * at runtime.
      */
-    issueUserCookie(
+    token?: string;
+};
+/**
+ * A response object for {@link UrlReaderService.readUrl} operations.
+ *
+ * @public
+ */
+type UrlReaderServiceReadUrlResponse = {
     /**
-     * An Express response object.
+     * Returns the data that was read from the remote URL.
      */
-    res: Response, 
+    buffer(): Promise<Buffer>;
     /**
-     * Optional further settings.
+     * Returns the data that was read from the remote URL as a Readable stream.
+     *
+     * @remarks
+     *
+     * This method will be required in a future release.
      */
-    options?: {
-        /**
-         * Issue the cookie for this specific credential. Must be a "user" type
-         * principal, or a "none" type (which leads to deleting the cookie).
-         *
-         * @remarks
-         *
-         * Normally you do not have to specify this option, because the default
-         * behavior is to extract the credentials from the request that
-         * corresponded to the given respnse.
-         */
-        credentials?: BackstageCredentials;
-    }): Promise<{
-        expiresAt: Date;
-    }>;
-}
-
-/**
- * @public
- */
-interface RootHealthService {
+    stream?(): Readable;
     /**
-     * Get the liveness status of the backend.
+     * Etag returned by content provider.
+     *
+     * @remarks
+     *
+     * Can be used to compare and cache responses when doing subsequent calls.
      */
-    getLiveness(): Promise<{
-        status: number;
-        payload?: JsonValue;
-    }>;
+    etag?: string;
     /**
-     * Get the readiness status of the backend.
+     * Last modified date of the file contents.
      */
-    getReadiness(): Promise<{
-        status: number;
-        payload?: JsonValue;
-    }>;
-}
-
+    lastModifiedAt?: Date;
+};
 /**
- * The DiscoveryService is used to provide a mechanism for backend
- * plugins to discover the endpoints for itself or other backend plugins.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/discovery | service documentation} for more details.
- *
- * @remarks
- *
- * The purpose of the discovery API is to allow for many different deployment
- * setups and routing methods through a central configuration, instead
- * of letting each individual plugin manage that configuration.
- *
- * Implementations of the discovery API can be as simple as a URL pattern
- * using the pluginId, but could also have overrides for individual plugins,
- * or query a separate discovery service.
+ * An options object for {@link UrlReaderService.readTree} operations.
  *
  * @public
  */
-interface DiscoveryService {
+type UrlReaderServiceReadTreeOptions = {
     /**
-     * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
+     * A filter that can be used to select which files should be included.
      *
      * @remarks
      *
-     * The returned URL should point to an internal endpoint for the plugin, with
-     * the shortest route possible. The URL should be used for service-to-service
-     * communication within a Backstage backend deployment.
+     * The path passed to the filter function is the relative path from the URL
+     * that the file tree is fetched from, without any leading '/'.
      *
-     * This method must always be called just before making each request, as opposed to
-     * fetching the URL once when constructing an API client. That is to ensure that more
-     * flexible routing patterns can be supported where a different result might be returned each time.
+     * For example, given the URL https://github.com/my/repo/tree/master/my-dir, a file
+     * at https://github.com/my/repo/blob/master/my-dir/my-subdir/my-file.txt will
+     * be represented as my-subdir/my-file.txt
      *
-     * For example, asking for the URL for `catalog` may return something
-     * like `http://10.1.2.3/api/catalog`
+     * If no filter is provided, all files are extracted.
      */
-    getBaseUrl(pluginId: string): Promise<string>;
+    filter?(path: string, info?: {
+        size: number;
+    }): boolean;
     /**
-     * Returns the external HTTP base backend URL for a given plugin, without a trailing slash.
+     * An ETag which can be provided to check whether a
+     * {@link UrlReaderService.readTree} response has changed from a previous execution.
      *
      * @remarks
      *
-     * The returned URL should point to an external endpoint for the plugin, such that
-     * it is reachable from the Backstage frontend and other external services. The returned
-     * URL should be usable for example as a callback / webhook URL.
+     * In the {@link UrlReaderService.readTree} response, an ETag is returned along with
+     * the tree blob. The ETag is a unique identifier of the tree blob, usually
+     * the commit SHA or ETag from the target.
      *
-     * The returned URL should be stable and in general not change unless other static
-     * or external configuration is changed. Changes should not come as a surprise
-     * to an operator of the Backstage backend.
+     * When an ETag is given as a request option, {@link UrlReaderService.readTree} will
+     * first compare the ETag against the ETag on the target branch. If they
+     * match, {@link UrlReaderService.readTree} will throw a
+     * {@link @backstage/errors#NotModifiedError} indicating that the response
+     * will not differ from the previous response which included this particular
+     * ETag. If they do not match, {@link UrlReaderService.readTree} will return the
+     * rest of the response along with a new ETag.
+     */
+    etag?: string;
+    /**
+     * An abort signal to pass down to the underlying request.
      *
-     * For example, asking for the URL for `catalog` may return something
-     * like `https://backstage.example.com/api/catalog`
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
      */
-    getExternalBaseUrl(pluginId: string): Promise<string>;
-}
-
+    signal?: AbortSignal;
+    /**
+     * An optional token to use for authentication when reading the resources.
+     *
+     * @remarks
+     *
+     * By default all URL Readers will use the integrations config which is supplied
+     * when creating the Readers. Sometimes it might be desireable to use the already
+     * created URLReaders but with a different token, maybe that's supplied by the user
+     * at runtime.
+     */
+    token?: string;
+};
 /**
- * Manages access to databases that plugins get.
+ * Options that control {@link UrlReaderServiceReadTreeResponse.dir} execution.
  *
- * See the {@link https://backstage.io/docs/backend-system/core-services/database | service documentation} for more details.
+ * @public
+ */
+type UrlReaderServiceReadTreeResponseDirOptions = {
+    /**
+     * The directory to write files to.
+     *
+     * @remarks
+     *
+     * Defaults to the OS tmpdir, or `backend.workingDirectory` if set in config.
+     */
+    targetDir?: string;
+};
+/**
+ * A response object for {@link UrlReaderService.readTree} operations.
  *
  * @public
  */
-interface DatabaseService {
+type UrlReaderServiceReadTreeResponse = {
     /**
-     * getClient provides backend plugins database connections for itself.
+     * Returns an array of all the files inside the tree, and corresponding
+     * functions to read their content.
+     */
+    files(): Promise<UrlReaderServiceReadTreeResponseFile[]>;
+    /**
+     * Returns the tree contents as a binary archive, using a stream.
+     */
+    archive(): Promise<NodeJS.ReadableStream>;
+    /**
+     * Extracts the tree response into a directory and returns the path of the
+     * directory.
      *
-     * The purpose of this method is to allow plugins to get isolated data
-     * stores so that plugins are discouraged from database integration.
+     * **NOTE**: It is the responsibility of the caller to remove the directory after use.
      */
-    getClient(): Promise<Knex>;
+    dir(options?: UrlReaderServiceReadTreeResponseDirOptions): Promise<string>;
     /**
-     * This property is used to control the behavior of database migrations.
+     * Etag returned by content provider.
+     *
+     * @remarks
+     *
+     * Can be used to compare and cache responses when doing subsequent calls.
      */
-    migrations?: {
-        /**
-         * skip database migrations. Useful if connecting to a read-only database.
-         *
-         * @defaultValue false
-         */
-        skip?: boolean;
-    };
-}
-
+    etag: string;
+};
 /**
- * Provides access to static configuration.
- *
- * See the {@link https://backstage.io/docs/conf/ | configuration documentation}
- * and the {@link https://backstage.io/docs/backend-system/core-services/root-config | service documentation}
- * for more details.
+ * Represents a single file in a {@link UrlReaderService.readTree} response.
  *
  * @public
  */
-interface RootConfigService extends Config {
-}
-
+type UrlReaderServiceReadTreeResponseFile = {
+    /**
+     * The filepath of the data.
+     */
+    path: string;
+    /**
+     * The binary contents of the file.
+     */
+    content(): Promise<Buffer>;
+    /**
+     * The last modified timestamp of the data.
+     */
+    lastModifiedAt?: Date;
+};
 /**
- * Options passed to {@link CacheService.set}.
+ * An options object for search operations.
  *
  * @public
  */
-type CacheServiceSetOptions = {
+type UrlReaderServiceSearchOptions = {
     /**
-     * Optional TTL (in milliseconds if given as a number). Defaults to the TTL provided when the client
-     * was set up (or no TTL if none are provided).
+     * An etag can be provided to check whether the search response has changed from a previous execution.
+     *
+     * In the search() response, an etag is returned along with the files. The etag is a unique identifier
+     * of the current tree, usually the commit SHA or etag from the target.
+     *
+     * When an etag is given in SearchOptions, search will first compare the etag against the etag
+     * on the target branch. If they match, search will throw a NotModifiedError indicating that the search
+     * response will not differ from the previous response which included this particular etag. If they mismatch,
+     * search will return the rest of SearchResponse along with a new etag.
      */
-    ttl?: number | HumanDuration;
+    etag?: string;
+    /**
+     * An abort signal to pass down to the underlying request.
+     *
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
+     */
+    signal?: AbortSignal;
+    /**
+     * An optional token to use for authentication when reading the resources.
+     *
+     * @remarks
+     *
+     * By default all URL Readers will use the integrations config which is supplied
+     * when creating the Readers. Sometimes it might be desireable to use the already
+     * created URLReaders but with a different token, maybe that's supplied by the user
+     * at runtime.
+     */
+    token?: string;
 };
 /**
- * Options passed to {@link CacheService.withOptions}.
+ * The output of a search operation.
  *
  * @public
  */
-type CacheServiceOptions = {
+type UrlReaderServiceSearchResponse = {
     /**
-     * An optional default TTL (in milliseconds if given as a number) to be set when getting a client
-     * instance. If not provided, data will persist indefinitely by default (or
-     * can be configured per entry at set-time).
+     * The files that matched the search query.
      */
-    defaultTtl?: number | HumanDuration;
+    files: UrlReaderServiceSearchResponseFile[];
+    /**
+     * A unique identifier of the current remote tree, usually the commit SHA or etag from the target.
+     */
+    etag: string;
 };
 /**
- * A pre-configured, storage agnostic cache service suitable for use by
- * Backstage plugins.
- *
- * See the {@link https://backstage.io/docs/backend-system/core-services/cache | service documentation} for more details.
+ * Represents a single file in a search response.
  *
  * @public
  */
-interface CacheService {
-    /**
-     * Reads data from a cache store for the given key. If no data was found,
-     * returns undefined.
-     */
-    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
+type UrlReaderServiceSearchResponseFile = {
     /**
-     * Writes the given data to a cache store, associated with the given key. An
-     * optional TTL may also be provided, otherwise it defaults to the TTL that
-     * was provided when the client was instantiated.
+     * The full URL to the file.
      */
-    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
+    url: string;
     /**
-     * Removes the given key from the cache store.
+     * The binary contents of the file.
      */
-    delete(key: string): Promise<void>;
+    content(): Promise<Buffer>;
     /**
-     * Creates a new {@link CacheService} instance with the given options.
+     * The last modified timestamp of the data.
      */
-    withOptions(options: CacheServiceOptions): CacheService;
-}
+    lastModifiedAt?: Date;
+};
 
 /**
  * Represents user information that is available to the backend, based on some
@@ -1587,6 +1734,16 @@ declare namespace coreServices {
      * @public
      */
     const logger: ServiceRef<LoggerService, "plugin", "singleton">;
+    /**
+     * Plugin-level auditing.
+     *
+     * See {@link AuditorService}
+     * and {@link https://backstage.io/docs/backend-system/core-services/auditor | the service docs}
+     * for more information.
+     *
+     * @public
+     */
+    const auditor: ServiceRef<AuditorService, "plugin", "singleton">;
     /**
      * Permission system integration for authorization of user actions.
      *
@@ -1597,6 +1754,16 @@ declare namespace coreServices {
      * @public
      */
     const permissions: ServiceRef<PermissionsService, "plugin", "singleton">;
+    /**
+     * Permission system integration for registering resources and permissions.
+     *
+     * See {@link PermissionsRegistryService}
+     * and {@link https://backstage.io/docs/backend-system/core-services/permission-integrations | the service docs}
+     * for more information.
+     *
+     * @public
+     */
+    const permissionsRegistry: ServiceRef<PermissionsRegistryService, "plugin", "singleton">;
     /**
      * Built-in service for accessing metadata about the current plugin.
      *
@@ -1845,4 +2012,4 @@ declare function createBackendFeatureLoader<TDeps extends {
     [name in string]: unknown;
 }>(options: CreateBackendFeatureLoaderOptions<TDeps>): BackendFeature;
 
-export { type AuthService, type BackendFeature, type BackendModuleRegistrationPoints, type BackendPluginRegistrationPoints, type BackstageCredentials, type BackstageNonePrincipal, type BackstagePrincipalAccessRestrictions, type BackstagePrincipalTypes, type BackstageServicePrincipal, type BackstageUserInfo, type BackstageUserPrincipal, type CacheService, type CacheServiceOptions, type CacheServiceSetOptions, type CreateBackendFeatureLoaderOptions, type CreateBackendModuleOptions, type CreateBackendPluginOptions, type CreateExtensionPointOptions, type DatabaseService, type DiscoveryService, type ExtensionPoint, type HttpAuthService, type HttpRouterService, type HttpRouterServiceAuthPolicy, type LifecycleService, type LifecycleServiceShutdownHook, type LifecycleServiceShutdownOptions, type LifecycleServiceStartupHook, type LifecycleServiceStartupOptions, type LoggerService, type PermissionsService, type PermissionsServiceRequestOptions, type PluginMetadataService, type PluginServiceFactoryOptions, type RootConfigService, type RootHealthService, type RootHttpRouterService, type RootLifecycleService, type RootLoggerService, type RootServiceFactoryOptions, type SchedulerService, type SchedulerServiceTaskDescriptor, type SchedulerServiceTaskFunction, type SchedulerServiceTaskInvocationDefinition, type SchedulerServiceTaskRunner, type SchedulerServiceTaskScheduleDefinition, type SchedulerServiceTaskScheduleDefinitionConfig, type ServiceFactory, type ServiceRef, type ServiceRefOptions, type UrlReaderService, type UrlReaderServiceReadTreeOptions, type UrlReaderServiceReadTreeResponse, type UrlReaderServiceReadTreeResponseDirOptions, type UrlReaderServiceReadTreeResponseFile, type UrlReaderServiceReadUrlOptions, type UrlReaderServiceReadUrlResponse, type UrlReaderServiceSearchOptions, type UrlReaderServiceSearchResponse, type UrlReaderServiceSearchResponseFile, type UserInfoService, coreServices, createBackendFeatureLoader, createBackendModule, createBackendPlugin, createExtensionPoint, createServiceFactory, createServiceRef, isDatabaseConflictError, readSchedulerServiceTaskScheduleDefinitionFromConfig, resolvePackagePath, resolveSafeChildPath };
+export { type AuditorService, type AuditorServiceCreateEventOptions, type AuditorServiceEvent, type AuditorServiceEventSeverityLevel, type AuthService, type BackendFeature, type BackendModuleRegistrationPoints, type BackendPluginRegistrationPoints, type BackstageCredentials, type BackstageNonePrincipal, type BackstagePrincipalAccessRestrictions, type BackstagePrincipalTypes, type BackstageServicePrincipal, type BackstageUserInfo, type BackstageUserPrincipal, type CacheService, type CacheServiceOptions, type CacheServiceSetOptions, type CreateBackendFeatureLoaderOptions, type CreateBackendModuleOptions, type CreateBackendPluginOptions, type CreateExtensionPointOptions, type DatabaseService, type DiscoveryService, type ExtensionPoint, type HttpAuthService, type HttpRouterService, type HttpRouterServiceAuthPolicy, type LifecycleService, type LifecycleServiceShutdownHook, type LifecycleServiceShutdownOptions, type LifecycleServiceStartupHook, type LifecycleServiceStartupOptions, type LoggerService, type PermissionsRegistryService, type PermissionsRegistryServiceAddResourceTypeOptions, type PermissionsService, type PermissionsServiceRequestOptions, type PluginMetadataService, type PluginServiceFactoryOptions, type RootConfigService, type RootHealthService, type RootHttpRouterService, type RootLifecycleService, type RootLoggerService, type RootServiceFactoryOptions, type SchedulerService, type SchedulerServiceTaskDescriptor, type SchedulerServiceTaskFunction, type SchedulerServiceTaskInvocationDefinition, type SchedulerServiceTaskRunner, type SchedulerServiceTaskScheduleDefinition, type SchedulerServiceTaskScheduleDefinitionConfig, type ServiceFactory, type ServiceRef, type ServiceRefOptions, type UrlReaderService, type UrlReaderServiceReadTreeOptions, type UrlReaderServiceReadTreeResponse, type UrlReaderServiceReadTreeResponseDirOptions, type UrlReaderServiceReadTreeResponseFile, type UrlReaderServiceReadUrlOptions, type UrlReaderServiceReadUrlResponse, type UrlReaderServiceSearchOptions, type UrlReaderServiceSearchResponse, type UrlReaderServiceSearchResponseFile, type UserInfoService, coreServices, createBackendFeatureLoader, createBackendModule, createBackendPlugin, createExtensionPoint, createServiceFactory, createServiceRef, isDatabaseConflictError, readSchedulerServiceTaskScheduleDefinitionFromConfig, resolvePackagePath, resolveSafeChildPath };