@cerbos/core - npm Package Compare versions

Comparing version 0.8.1 to 0.9.0

lib/client.d.ts

 import type { _RPC, _Request, _Response, _Service } from "./rpcs";
-import type { AddOrUpdatePoliciesRequest, AddOrUpdateSchemasRequest, CheckResourceRequest, CheckResourcesRequest, CheckResourcesResponse, CheckResourcesResult, DeleteSchemasRequest, GetPoliciesRequest, GetPoliciesResponse, GetSchemasRequest, GetSchemasResponse, IsAllowedRequest, ListPoliciesResponse, ListSchemasResponse, PlanResourcesRequest, PlanResourcesResponse, Policy, ReloadStoreRequest, Schema, ServerInfo, ValidationFailedCallback } from "./types/external";
+import type { AddOrUpdatePoliciesRequest, AddOrUpdateSchemasRequest, CheckResourceRequest, CheckResourcesRequest, CheckResourcesResponse, CheckResourcesResult, DeleteSchemasRequest, DeleteSchemasResponse, DisablePoliciesRequest, DisablePoliciesResponse, GetPoliciesRequest, GetPoliciesResponse, GetSchemasRequest, GetSchemasResponse, IsAllowedRequest, ListPoliciesResponse, ListSchemasResponse, PlanResourcesRequest, PlanResourcesResponse, Policy, ReloadStoreRequest, Schema, ServerInfo, ValidationFailedCallback } from "./types/external";
 /** @internal */
 export type _Transport = <Service extends _Service, RPC extends _RPC<Service>>(service: Service, rpc: RPC, request: _Request<Service, RPC>, adminCredentials?: AdminCredentials) => Promise<_Response<Service, RPC>>;
+/** @internal */
+export type _Instrumenter = (transport: _Transport) => _Transport;
+/** @internal */
+export declare const _addInstrumenter: (instrumenter: _Instrumenter) => void;
+/** @internal */
+export declare const _removeInstrumenter: (instrumenter: _Instrumenter) => void;
 /**
@@ -60,4 +66,4 @@ * Options for creating a new {@link Client}.
 export declare abstract class Client {
+    private readonly options;
     private readonly transport;
-    private readonly options;
     /** @internal */
@@ -190,12 +196,16 @@ protected constructor(transport: _Transport, options: Options);
      *
-     * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
      *
      * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
      *
+     * The way this method handles failure depends on the version of the connected PDP server.
+     * When the server is running Cerbos v0.25 or later, it returns `true` if the schema was deleted and `false` if the schema was not found.
+     * With earlier versions of Cerbos, it throws an error if the schema was not found, and returns successfully if the schema was deleted; the returned value should be ignored.
+     *
      * @example
      * ```typescript
-     * await cerbos.deleteSchema("document.json");
+     * const deleted = await cerbos.deleteSchema("document.json");
      * ```
      */
-    deleteSchema(id: string): Promise<void>;
+    deleteSchema(id: string): Promise<boolean>;
     /**
@@ -209,9 +219,13 @@ * Delete multiple schemas.
      *
-     * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
      *
      * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
      *
+     * The way this method handles failure depends on the version of the connected PDP server.
+     * When the server is running Cerbos v0.25 or later, it returns a {@link DeleteSchemasResponse} that includes the number of schemas that were deleted.
+     * With earlier versions of Cerbos, it throws an error if no schemas were found, and returns successfully if at least one schema was deleted; the returned value should be ignored.
+     *
      * @example
      * ```typescript
-     * await cerbos.deleteSchemas({
+     * const result = await cerbos.deleteSchemas({
      *   ids: ["document.json", "image.json"],
@@ -221,4 +235,42 @@ * });
      */
-    deleteSchemas(request: DeleteSchemasRequest): Promise<void>;
+    deleteSchemas(request: DeleteSchemasRequest): Promise<DeleteSchemasResponse>;
     /**
+     * Disable multiple policies.
+     *
+     * @remarks
+     * Requires
+     *
+     * - the client to be configured with {@link Options.adminCredentials},
+     *
+     * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     *
+     * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+     *
+     * @example
+     * ```typescript
+     * const result = await cerbos.disablePolicies({
+     *   ids: ["resource.document.v1", "resource.image.v1"],
+     * });
+     * ```
+     */
+    disablePolicies(request: DisablePoliciesRequest): Promise<DisablePoliciesResponse>;
+    /**
+     * Disable a policy.
+     *
+     * @remarks
+     * Requires
+     *
+     * - the client to be configured with {@link Options.adminCredentials},
+     *
+     * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     *
+     * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+     *
+     * @example
+     * ```typescript
+     * const disabled = await cerbos.disablePolicy("resource.document.v1");
+     * ```
+     */
+    disablePolicy(id: string): Promise<boolean>;
+    /**
      * Fetch multiple policies by ID.
@@ -356,2 +408,3 @@ *
      *   resource: { kind: "document" },
+     *   action: "view",
      * });
@@ -358,0 +411,0 @@ * ```

lib/client.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = void 0;
+exports.Client = exports._removeInstrumenter = exports._addInstrumenter = void 0;
 const fromProtobuf_1 = require("./convert/fromProtobuf");
 const toProtobuf_1 = require("./convert/toProtobuf");
 const errors_1 = require("./errors");
+const instrumenters = new Set();
+/** @internal */
+const _addInstrumenter = (instrumenter) => {
+    instrumenters.add(instrumenter);
+};
+exports._addInstrumenter = _addInstrumenter;
+/** @internal */
+const _removeInstrumenter = (instrumenter) => {
+    instrumenters.delete(instrumenter);
+};
+exports._removeInstrumenter = _removeInstrumenter;
 /**
@@ -15,4 +26,7 @@ * Base implementation of a client for interacting with the Cerbos policy decision point server.
     constructor(transport, options) {
+        this.options = options;
         this.transport = transport;
-        this.options = options;
+        for (const instrumenter of instrumenters) {
+            this.transport = instrumenter(this.transport);
+        }
     }
@@ -163,13 +177,18 @@ /**
      *
-     * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
      *
      * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
      *
+     * The way this method handles failure depends on the version of the connected PDP server.
+     * When the server is running Cerbos v0.25 or later, it returns `true` if the schema was deleted and `false` if the schema was not found.
+     * With earlier versions of Cerbos, it throws an error if the schema was not found, and returns successfully if the schema was deleted; the returned value should be ignored.
+     *
      * @example
      * ```typescript
-     * await cerbos.deleteSchema("document.json");
+     * const deleted = await cerbos.deleteSchema("document.json");
      * ```
      */
     async deleteSchema(id) {
-        await this.deleteSchemas({ ids: [id] });
+        const { deletedSchemas } = await this.deleteSchemas({ ids: [id] });
+        return deletedSchemas === 1;
     }
@@ -184,9 +203,13 @@ /**
      *
-     * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
      *
      * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
      *
+     * The way this method handles failure depends on the version of the connected PDP server.
+     * When the server is running Cerbos v0.25 or later, it returns a {@link DeleteSchemasResponse} that includes the number of schemas that were deleted.
+     * With earlier versions of Cerbos, it throws an error if no schemas were found, and returns successfully if at least one schema was deleted; the returned value should be ignored.
+     *
      * @example
      * ```typescript
-     * await cerbos.deleteSchemas({
+     * const result = await cerbos.deleteSchemas({
      *   ids: ["document.json", "image.json"],
@@ -197,5 +220,48 @@ * });
     async deleteSchemas(request) {
-        await this.admin("deleteSchema", (0, toProtobuf_1.deleteSchemasRequestToProtobuf)(request));
+        return (0, fromProtobuf_1.deleteSchemasResponseFromProtobuf)(await this.admin("deleteSchema", (0, toProtobuf_1.deleteSchemasRequestToProtobuf)(request)));
     }
     /**
+     * Disable multiple policies.
+     *
+     * @remarks
+     * Requires
+     *
+     * - the client to be configured with {@link Options.adminCredentials},
+     *
+     * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     *
+     * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+     *
+     * @example
+     * ```typescript
+     * const result = await cerbos.disablePolicies({
+     *   ids: ["resource.document.v1", "resource.image.v1"],
+     * });
+     * ```
+     */
+    async disablePolicies(request) {
+        return (0, fromProtobuf_1.disablePoliciesResponseFromProtobuf)(await this.admin("disablePolicy", (0, toProtobuf_1.disablePoliciesRequestToProtobuf)(request)));
+    }
+    /**
+     * Disable a policy.
+     *
+     * @remarks
+     * Requires
+     *
+     * - the client to be configured with {@link Options.adminCredentials},
+     *
+     * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+     *
+     * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+     *
+     * @example
+     * ```typescript
+     * const disabled = await cerbos.disablePolicy("resource.document.v1");
+     * ```
+     */
+    async disablePolicy(id) {
+        const { disabledPolicies } = await this.disablePolicies({ ids: [id] });
+        return disabledPolicies === 1;
+    }
+    /**
      * Fetch multiple policies by ID.
@@ -355,2 +421,3 @@ *
      *   resource: { kind: "document" },
+     *   action: "view",
      * });
@@ -387,10 +454,10 @@ * ```
      */
-    serverInfo() {
-        return this.cerbos("serverInfo", {});
+    async serverInfo() {
+        return await this.cerbos("serverInfo", {});
     }
-    admin(rpc, request) {
-        return this.transport("admin", rpc, request, this.options.adminCredentials);
+    async admin(rpc, request) {
+        return await this.transport("admin", rpc, request, this.options.adminCredentials);
     }
-    cerbos(rpc, request) {
-        return this.transport("cerbos", rpc, request);
+    async cerbos(rpc, request) {
+        return await this.transport("cerbos", rpc, request);
     }
@@ -397,0 +464,0 @@ handleValidationErrors({ validationErrors, }) {

lib/convert/fromProtobuf.d.ts

@@ -1,6 +0,9 @@
-import type { CheckResourcesResponse as CheckResourcesResponseProtobuf, GetPolicyResponse, GetSchemaResponse, ListPoliciesResponse as ListPoliciesResponseProtobuf, ListSchemasResponse as ListSchemasResponseProtobuf, PlanResourcesResponse as PlanResourcesResponseProtobuf } from "../protobuf/cerbos/response/v1/response";
-import type { GetPoliciesResponse, ListPoliciesResponse, ListSchemasResponse, PlanResourcesResponse } from "../types/external";
+import type { CheckResourcesResponse as CheckResourcesResponseProtobuf, DeleteSchemaResponse, DisablePolicyResponse, GetPolicyResponse, GetSchemaResponse, ListPoliciesResponse as ListPoliciesResponseProtobuf, ListSchemasResponse as ListSchemasResponseProtobuf, PlanResourcesResponse as PlanResourcesResponseProtobuf } from "../protobuf/cerbos/response/v1/response";
+import type { DisablePoliciesResponse, GetPoliciesResponse, ListPoliciesResponse, ListSchemasResponse, PlanResourcesResponse } from "../types/external";
 import { CheckResourcesResponse } from "../types/external";
+import type { DeleteSchemasResponse } from "../types/external/DeleteSchemasResponse";
 import type { GetSchemasResponse } from "../types/external/GetSchemasResponse";
 export declare const checkResourcesResponseFromProtobuf: ({ requestId, results, }: CheckResourcesResponseProtobuf) => CheckResourcesResponse;
+export declare const deleteSchemasResponseFromProtobuf: ({ deletedSchemas, }: DeleteSchemaResponse) => DeleteSchemasResponse;
+export declare const disablePoliciesResponseFromProtobuf: ({ disabledPolicies, }: DisablePolicyResponse) => DisablePoliciesResponse;
 export declare const getPoliciesResponseFromProtobuf: ({ policies, }: GetPolicyResponse) => GetPoliciesResponse;
@@ -7,0 +10,0 @@ export declare const getSchemasResponseFromProtobuf: ({ schemas, }: GetSchemaResponse) => GetSchemasResponse;

lib/convert/fromProtobuf.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.planResourcesResponseFromProtobuf = exports.listSchemasResponseFromProtobuf = exports.listPoliciesResponseFromProtobuf = exports.getSchemasResponseFromProtobuf = exports.getPoliciesResponseFromProtobuf = exports.checkResourcesResponseFromProtobuf = void 0;
+exports.planResourcesResponseFromProtobuf = exports.listSchemasResponseFromProtobuf = exports.listPoliciesResponseFromProtobuf = exports.getSchemasResponseFromProtobuf = exports.getPoliciesResponseFromProtobuf = exports.disablePoliciesResponseFromProtobuf = exports.deleteSchemasResponseFromProtobuf = exports.checkResourcesResponseFromProtobuf = void 0;
 const effect_1 = require("../protobuf/cerbos/effect/v1/effect");
@@ -44,2 +44,10 @@ const engine_1 = require("../protobuf/cerbos/engine/v1/engine");
 };
+const deleteSchemasResponseFromProtobuf = ({ deletedSchemas, }) => ({
+    deletedSchemas,
+});
+exports.deleteSchemasResponseFromProtobuf = deleteSchemasResponseFromProtobuf;
+const disablePoliciesResponseFromProtobuf = ({ disabledPolicies, }) => ({
+    disabledPolicies,
+});
+exports.disablePoliciesResponseFromProtobuf = disablePoliciesResponseFromProtobuf;
 const getPoliciesResponseFromProtobuf = ({ policies, }) => ({
@@ -53,6 +61,13 @@ policies: policies.map(policyFromProtobuf),
     disabled,
-    metadata,
+    metadata: metadata && policyMetadataFromProtobuf(metadata),
     variables,
     ...policyTypeFromProtobuf(policyType),
 });
+const policyMetadataFromProtobuf = ({ annotations, hash, sourceFile, storeIdentifer, storeIdentifier, }) => ({
+    annotations,
+    hash,
+    sourceFile,
+    storeIdentifer: storeIdentifier || storeIdentifer,
+    storeIdentifier: storeIdentifier || storeIdentifer,
+});
 const policyTypeFromProtobuf = (policyType) => {
@@ -59,0 +74,0 @@ if (!policyType) {

lib/convert/toProtobuf.d.ts

@@ -1,3 +0,4 @@
-import type { AddOrUpdatePolicyRequest, AddOrUpdateSchemaRequest, CheckResourcesRequest as CheckResourcesRequestProtobuf, DeleteSchemaRequest, GetPolicyRequest, GetSchemaRequest, PlanResourcesRequest as PlanResourcesRequestProtobuf } from "../protobuf/cerbos/request/v1/request";
+import type { AddOrUpdatePolicyRequest, AddOrUpdateSchemaRequest, CheckResourcesRequest as CheckResourcesRequestProtobuf, DeleteSchemaRequest, DisablePolicyRequest, GetPolicyRequest, GetSchemaRequest, PlanResourcesRequest as PlanResourcesRequestProtobuf } from "../protobuf/cerbos/request/v1/request";
 import type { AddOrUpdatePoliciesRequest, AddOrUpdateSchemasRequest, CheckResourcesRequest, DeleteSchemasRequest, GetPoliciesRequest, PlanResourcesRequest } from "../types/external";
+import type { DisablePoliciesRequest } from "../types/external/DisablePoliciesRequest";
 import type { GetSchemasRequest } from "../types/external/GetSchemasRequest";
@@ -8,2 +9,3 @@ export declare const addOrUpdatePoliciesRequestToProtobuf: ({ policies, }: AddOrUpdatePoliciesRequest) => AddOrUpdatePolicyRequest;
 export declare const deleteSchemasRequestToProtobuf: ({ ids, }: DeleteSchemasRequest) => DeleteSchemaRequest;
+export declare const disablePoliciesRequestToProtobuf: ({ ids, }: DisablePoliciesRequest) => DisablePolicyRequest;
 export declare const getPoliciesRequestToProtobuf: ({ ids, }: GetPoliciesRequest) => GetPolicyRequest;
@@ -10,0 +12,0 @@ export declare const getSchemasRequestToProtobuf: ({ ids, }: GetSchemasRequest) => GetSchemaRequest;

lib/convert/toProtobuf.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.planResourcesRequestToProtobuf = exports.getSchemasRequestToProtobuf = exports.getPoliciesRequestToProtobuf = exports.deleteSchemasRequestToProtobuf = exports.checkResourcesRequestToProtobuf = exports.addOrUpdateSchemasRequestToProtobuf = exports.addOrUpdatePoliciesRequestToProtobuf = void 0;
+exports.planResourcesRequestToProtobuf = exports.getSchemasRequestToProtobuf = exports.getPoliciesRequestToProtobuf = exports.disablePoliciesRequestToProtobuf = exports.deleteSchemasRequestToProtobuf = exports.checkResourcesRequestToProtobuf = exports.addOrUpdateSchemasRequestToProtobuf = exports.addOrUpdatePoliciesRequestToProtobuf = void 0;
 const uuid_1 = require("uuid");
@@ -18,8 +18,3 @@ const effect_1 = require("../protobuf/cerbos/effect/v1/effect");
         disabled,
-        metadata: {
-            annotations: {},
-            hash: undefined,
-            storeIdentifer: "",
-            sourceFile: "",
-        },
+        metadata: undefined,
         policyType: policyTypeToProtobuf(policy),
@@ -203,2 +198,6 @@ variables,
 exports.deleteSchemasRequestToProtobuf = deleteSchemasRequestToProtobuf;
+const disablePoliciesRequestToProtobuf = ({ ids, }) => ({
+    id: ids,
+});
+exports.disablePoliciesRequestToProtobuf = disablePoliciesRequestToProtobuf;
 const getPoliciesRequestToProtobuf = ({ ids, }) => ({
@@ -205,0 +204,0 @@ id: ids,

lib/protobuf/cerbos/audit/v1/audit.d.ts

@@ -34,2 +34,5 @@ import type { CheckInput, CheckOutput, PlanResourcesInput, PlanResourcesOutput } from "../../engine/v1/engine";
     };
+    metadata: {
+        [key: string]: MetaValues;
+    };
 }
@@ -46,2 +49,6 @@ export interface DecisionLogEntry_CheckResources {
 }
+export interface DecisionLogEntry_MetadataEntry {
+    key: string;
+    value: MetaValues | undefined;
+}
 export interface MetaValues {
@@ -48,0 +55,0 @@ values: string[];

lib/protobuf/cerbos/policy/v1/policy.d.ts

@@ -33,3 +33,5 @@ import type { Effect } from "../../effect/v1/effect";
     hash: string | undefined;
+    /** @deprecated */
     storeIdentifer: string;
+    storeIdentifier: string;
 }
@@ -36,0 +38,0 @@ export interface Metadata_AnnotationsEntry {

lib/protobuf/cerbos/request/v1/request.d.ts

@@ -146,2 +146,5 @@ import type { Duration } from "../../../google/protobuf/duration";
 }
+export interface DisablePolicyRequest {
+    id: string[];
+}
 export interface AddOrUpdateSchemaRequest {
@@ -148,0 +151,0 @@ schemas: Schema[];

lib/protobuf/cerbos/response/v1/response.d.ts

@@ -210,2 +210,5 @@ import type { Empty } from "../../../google/protobuf/empty";
 }
+export interface DisablePolicyResponse {
+    disabledPolicies: number;
+}
 export interface AddOrUpdateSchemaResponse {
@@ -220,2 +223,3 @@ }
 export interface DeleteSchemaResponse {
+    deletedSchemas: number;
 }
@@ -222,0 +226,0 @@ export interface ReloadStoreResponse {

lib/rpcs.d.ts

@@ -1,3 +0,3 @@
-import type { AddOrUpdatePolicyRequest, AddOrUpdateSchemaRequest, CheckResourcesRequest, DeleteSchemaRequest, GetPolicyRequest, GetSchemaRequest, ListPoliciesRequest, ListSchemasRequest, PlanResourcesRequest, ReloadStoreRequest, ServerInfoRequest } from "./protobuf/cerbos/request/v1/request";
-import type { AddOrUpdatePolicyResponse, AddOrUpdateSchemaResponse, CheckResourcesResponse, DeleteSchemaResponse, GetPolicyResponse, GetSchemaResponse, ListPoliciesResponse, ListSchemasResponse, PlanResourcesResponse, ReloadStoreResponse, ServerInfoResponse } from "./protobuf/cerbos/response/v1/response";
+import type { AddOrUpdatePolicyRequest, AddOrUpdateSchemaRequest, CheckResourcesRequest, DeleteSchemaRequest, DisablePolicyRequest, GetPolicyRequest, GetSchemaRequest, ListPoliciesRequest, ListSchemasRequest, PlanResourcesRequest, ReloadStoreRequest, ServerInfoRequest } from "./protobuf/cerbos/request/v1/request";
+import type { AddOrUpdatePolicyResponse, AddOrUpdateSchemaResponse, CheckResourcesResponse, DeleteSchemaResponse, DisablePolicyResponse, GetPolicyResponse, GetSchemaResponse, ListPoliciesResponse, ListSchemasResponse, PlanResourcesResponse, ReloadStoreResponse, ServerInfoResponse } from "./protobuf/cerbos/response/v1/response";
 /** @internal */
@@ -9,2 +9,3 @@ export interface _Services {
         deleteSchema: [DeleteSchemaRequest, DeleteSchemaResponse];
+        disablePolicy: [DisablePolicyRequest, DisablePolicyResponse];
         getPolicy: [GetPolicyRequest, GetPolicyResponse];
@@ -11,0 +12,0 @@ getSchema: [GetSchemaRequest, GetSchemaResponse];

lib/types/external/index.d.ts

@@ -13,4 +13,7 @@ export * from "./AddOrUpdatePoliciesRequest";
 export * from "./DeleteSchemasRequest";
+export * from "./DeleteSchemasResponse";
 export * from "./DerivedRoleDefinition";
 export * from "./DerivedRoles";
+export * from "./DisablePoliciesRequest";
+export * from "./DisablePoliciesResponse";
 export * from "./Effect";
@@ -17,0 +20,0 @@ export * from "./GetPoliciesRequest";

lib/types/external/index.js

@@ -29,4 +29,7 @@ "use strict";
 __exportStar(require("./DeleteSchemasRequest"), exports);
+__exportStar(require("./DeleteSchemasResponse"), exports);
 __exportStar(require("./DerivedRoleDefinition"), exports);
 __exportStar(require("./DerivedRoles"), exports);
+__exportStar(require("./DisablePoliciesRequest"), exports);
+__exportStar(require("./DisablePoliciesResponse"), exports);
 __exportStar(require("./Effect"), exports);
@@ -33,0 +36,0 @@ __exportStar(require("./GetPoliciesRequest"), exports);

lib/types/external/PolicyBase.d.ts

@@ -8,8 +8,27 @@ import type { PolicyMetadata } from "./PolicyMetadata";
 export interface PolicyBase {
+    /**
+     * API version of the policy.
+     */
     apiVersion?: string;
+    /**
+     * Description of the policy.
+     */
     description?: string;
+    /**
+     * Whether the policy is ignored by the Cerbos engine.
+     */
     disabled?: boolean;
+    /**
+     * Metadata about the policy.
+     */
     metadata?: PolicyMetadata | undefined;
+    /**
+     * Variable expressions defined for the policy.
+     *
+     * @remarks
+     * Each variable is evaluated before any rule condition.
+     * A variable expression can contain anything that condition expression can have.
+     */
     variables?: Record<string, string>;
 }
 //# sourceMappingURL=PolicyBase.d.ts.map

lib/types/external/PolicyMetadata.d.ts

@@ -7,7 +7,25 @@ /**
 export interface PolicyMetadata {
+    /**
+     * The source of the policy, for auditing purposes.
+     */
     sourceFile: string;
+    /**
+     * Free-form data, for auditing purposes.
+     */
     annotations: Record<string, string | undefined>;
+    /**
+     * Hash of policy contents.
+     */
     hash: string | undefined;
+    /**
+     * Deprecated.
+     *
+     * @deprecated Use {@link PolicyMetadata.storeIdentifier} instead.
+     */
     storeIdentifer: string;
+    /**
+     * The policy's identifier in the backend store.
+     */
+    storeIdentifier: string;
 }
 //# sourceMappingURL=PolicyMetadata.d.ts.map

package.json

 {
   "name": "@cerbos/core",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Common types used by the @cerbos/grpc and @cerbos/http client libraries",
@@ -30,3 +30,6 @@ "repository": {
     "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/uuid": "9.0.0"
   }
 }

src/client.ts

 import {
   checkResourcesResponseFromProtobuf,
+  deleteSchemasResponseFromProtobuf,
+  disablePoliciesResponseFromProtobuf,
   getPoliciesResponseFromProtobuf,
@@ -14,2 +16,3 @@ getSchemasResponseFromProtobuf,
   deleteSchemasRequestToProtobuf,
+  disablePoliciesRequestToProtobuf,
   getPoliciesRequestToProtobuf,
@@ -29,2 +32,5 @@ getSchemasRequestToProtobuf,
   DeleteSchemasRequest,
+  DeleteSchemasResponse,
+  DisablePoliciesRequest,
+  DisablePoliciesResponse,
   GetPoliciesRequest,
@@ -55,2 +61,17 @@ GetPoliciesResponse,
 
+/** @internal */
+export type _Instrumenter = (transport: _Transport) => _Transport;
+
+const instrumenters = new Set<_Instrumenter>();
+
+/** @internal */
+export const _addInstrumenter = (instrumenter: _Instrumenter): void => {
+  instrumenters.add(instrumenter);
+};
+
+/** @internal */
+export const _removeInstrumenter = (instrumenter: _Instrumenter): void => {
+  instrumenters.delete(instrumenter);
+};
+
 /**
@@ -116,7 +137,14 @@ * Options for creating a new {@link Client}.
 export abstract class Client {
+  private readonly transport: _Transport;
+
   /** @internal */
   protected constructor(
-    private readonly transport: _Transport,
+    transport: _Transport,
     private readonly options: Options
-  ) {}
+  ) {
+    this.transport = transport;
+    for (const instrumenter of instrumenters) {
+      this.transport = instrumenter(this.transport);
+    }
+  }
 
@@ -295,13 +323,18 @@ /**
    *
-   * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+   * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
    *
    * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
    *
+   * The way this method handles failure depends on the version of the connected PDP server.
+   * When the server is running Cerbos v0.25 or later, it returns `true` if the schema was deleted and `false` if the schema was not found.
+   * With earlier versions of Cerbos, it throws an error if the schema was not found, and returns successfully if the schema was deleted; the returned value should be ignored.
+   *
    * @example
    * ```typescript
-   * await cerbos.deleteSchema("document.json");
+   * const deleted = await cerbos.deleteSchema("document.json");
    * ```
    */
-  public async deleteSchema(id: string): Promise<void> {
-    await this.deleteSchemas({ ids: [id] });
+  public async deleteSchema(id: string): Promise<boolean> {
+    const { deletedSchemas } = await this.deleteSchemas({ ids: [id] });
+    return deletedSchemas === 1;
   }
@@ -317,9 +350,13 @@
    *
-   * - the Cerbos policy decision point server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+   * - the Cerbos policy decision point (PDP) server to be configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
    *
    * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
    *
+   * The way this method handles failure depends on the version of the connected PDP server.
+   * When the server is running Cerbos v0.25 or later, it returns a {@link DeleteSchemasResponse} that includes the number of schemas that were deleted.
+   * With earlier versions of Cerbos, it throws an error if no schemas were found, and returns successfully if at least one schema was deleted; the returned value should be ignored.
+   *
    * @example
    * ```typescript
-   * await cerbos.deleteSchemas({
+   * const result = await cerbos.deleteSchemas({
    *   ids: ["document.json", "image.json"],
@@ -329,7 +366,63 @@ * });
    */
-  public async deleteSchemas(request: DeleteSchemasRequest): Promise<void> {
-    await this.admin("deleteSchema", deleteSchemasRequestToProtobuf(request));
+  public async deleteSchemas(
+    request: DeleteSchemasRequest
+  ): Promise<DeleteSchemasResponse> {
+    return deleteSchemasResponseFromProtobuf(
+      await this.admin("deleteSchema", deleteSchemasRequestToProtobuf(request))
+    );
   }
 
   /**
+   * Disable multiple policies.
+   *
+   * @remarks
+   * Requires
+   *
+   * - the client to be configured with {@link Options.adminCredentials},
+   *
+   * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+   *
+   * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+   *
+   * @example
+   * ```typescript
+   * const result = await cerbos.disablePolicies({
+   *   ids: ["resource.document.v1", "resource.image.v1"],
+   * });
+   * ```
+   */
+  public async disablePolicies(
+    request: DisablePoliciesRequest
+  ): Promise<DisablePoliciesResponse> {
+    return disablePoliciesResponseFromProtobuf(
+      await this.admin(
+        "disablePolicy",
+        disablePoliciesRequestToProtobuf(request)
+      )
+    );
+  }
+
+  /**
+   * Disable a policy.
+   *
+   * @remarks
+   * Requires
+   *
+   * - the client to be configured with {@link Options.adminCredentials},
+   *
+   * - the Cerbos policy decision point server to be at least v0.25 and configured with the {@link https://docs.cerbos.dev/cerbos/latest/api/admin_api.html | admin API} enabled, and
+   *
+   * - a dynamic {@link https://docs.cerbos.dev/cerbos/latest/configuration/storage.html | storage backend}.
+   *
+   * @example
+   * ```typescript
+   * const disabled = await cerbos.disablePolicy("resource.document.v1");
+   * ```
+   */
+  public async disablePolicy(id: string): Promise<boolean> {
+    const { disabledPolicies } = await this.disablePolicies({ ids: [id] });
+    return disabledPolicies === 1;
+  }
+
+  /**
    * Fetch multiple policies by ID.
@@ -514,2 +607,3 @@ *
    *   resource: { kind: "document" },
+   *   action: "view",
    * });
@@ -557,18 +651,23 @@ * ```
    */
-  public serverInfo(): Promise<ServerInfo> {
-    return this.cerbos("serverInfo", {});
+  public async serverInfo(): Promise<ServerInfo> {
+    return await this.cerbos("serverInfo", {});
   }
 
-  private admin<RPC extends _RPC<"admin">>(
+  private async admin<RPC extends _RPC<"admin">>(
     rpc: RPC,
     request: _Request<"admin", RPC>
   ): Promise<_Response<"admin", RPC>> {
-    return this.transport("admin", rpc, request, this.options.adminCredentials);
+    return await this.transport(
+      "admin",
+      rpc,
+      request,
+      this.options.adminCredentials
+    );
   }
 
-  private cerbos<RPC extends _RPC<"cerbos">>(
+  private async cerbos<RPC extends _RPC<"cerbos">>(
     rpc: RPC,
     request: _Request<"cerbos", RPC>
   ): Promise<_Response<"cerbos", RPC>> {
-    return this.transport("cerbos", rpc, request);
+    return await this.transport("cerbos", rpc, request);
   }
@@ -575,0 +674,0 @@

src/convert/fromProtobuf.ts

@@ -9,2 +9,3 @@ import { Effect as EffectProtobuf } from "../protobuf/cerbos/effect/v1/effect";
   Match_ExprList,
+  Metadata,
   Policy as PolicyProtobuf,
@@ -23,2 +24,4 @@ PrincipalPolicy as PrincipalPolicyProtobuf,
   CheckResourcesResponse_ResultEntry,
+  DeleteSchemaResponse,
+  DisablePolicyResponse,
   GetPolicyResponse,
@@ -40,2 +43,3 @@ GetSchemaResponse,
   DerivedRoles,
+  DisablePoliciesResponse,
   GetPoliciesResponse,
@@ -51,2 +55,3 @@ ListPoliciesResponse,
   PolicyBase,
+  PolicyMetadata,
   PrincipalPolicy,
@@ -74,2 +79,3 @@ PrincipalRule,
 } from "../types/external";
+import type { DeleteSchemasResponse } from "../types/external/DeleteSchemasResponse";
 import type { GetSchemasResponse } from "../types/external/GetSchemasResponse";
@@ -147,2 +153,14 @@ import type { OmitFromEach } from "../types/internal";
 
+export const deleteSchemasResponseFromProtobuf = ({
+  deletedSchemas,
+}: DeleteSchemaResponse): DeleteSchemasResponse => ({
+  deletedSchemas,
+});
+
+export const disablePoliciesResponseFromProtobuf = ({
+  disabledPolicies,
+}: DisablePolicyResponse): DisablePoliciesResponse => ({
+  disabledPolicies,
+});
+
 export const getPoliciesResponseFromProtobuf = ({
@@ -165,3 +183,3 @@ policies,
   disabled,
-  metadata,
+  metadata: metadata && policyMetadataFromProtobuf(metadata),
   variables,
@@ -171,2 +189,16 @@ ...policyTypeFromProtobuf(policyType),
 
+const policyMetadataFromProtobuf = ({
+  annotations,
+  hash,
+  sourceFile,
+  storeIdentifer,
+  storeIdentifier,
+}: Metadata): PolicyMetadata => ({
+  annotations,
+  hash,
+  sourceFile,
+  storeIdentifer: storeIdentifier || storeIdentifer,
+  storeIdentifier: storeIdentifier || storeIdentifer,
+});
+
 type OmitPolicyBase<T extends Policy> = OmitFromEach<T, keyof PolicyBase>;
@@ -173,0 +205,0 @@

src/convert/toProtobuf.ts

@@ -32,2 +32,3 @@ import { v4 as uuidv4 } from "uuid";
   DeleteSchemaRequest,
+  DisablePolicyRequest,
   GetPolicyRequest,
@@ -78,2 +79,3 @@ GetSchemaRequest,
 } from "../types/external";
+import type { DisablePoliciesRequest } from "../types/external/DisablePoliciesRequest";
 import type { GetSchemasRequest } from "../types/external/GetSchemasRequest";
@@ -101,8 +103,3 @@
     disabled,
-    metadata: {
-      annotations: {},
-      hash: undefined,
-      storeIdentifer: "",
-      sourceFile: "",
-    },
+    metadata: undefined,
     policyType: policyTypeToProtobuf(policy),
@@ -386,2 +383,8 @@ variables,
 
+export const disablePoliciesRequestToProtobuf = ({
+  ids,
+}: DisablePoliciesRequest): DisablePolicyRequest => ({
+  id: ids,
+});
+
 export const getPoliciesRequestToProtobuf = ({
@@ -388,0 +391,0 @@ ids,

src/protobuf/cerbos/audit/v1/audit.ts

@@ -36,2 +36,3 @@ /* eslint-disable */
   };
+  metadata: { [key: string]: MetaValues };
 }
@@ -51,2 +52,7 @@
 
+export interface DecisionLogEntry_MetadataEntry {
+  key: string;
+  value: MetaValues | undefined;
+}
+
 export interface MetaValues {
@@ -53,0 +59,0 @@ values: string[];

src/protobuf/cerbos/policy/v1/policy.ts

@@ -27,4 +27,8 @@ /* eslint-disable */
   annotations: { [key: string]: string };
-  hash: string | undefined;
+  hash:
+    | string
+    | undefined;
+  /** @deprecated */
   storeIdentifer: string;
+  storeIdentifier: string;
 }
@@ -31,0 +35,0 @@

src/protobuf/cerbos/request/v1/request.ts

@@ -152,2 +152,6 @@ /* eslint-disable */
 
+export interface DisablePolicyRequest {
+  id: string[];
+}
+
 export interface AddOrUpdateSchemaRequest {
@@ -154,0 +158,0 @@ schemas: Schema[];

src/protobuf/cerbos/response/v1/response.ts

@@ -209,2 +209,6 @@ /* eslint-disable */
 
+export interface DisablePolicyResponse {
+  disabledPolicies: number;
+}
+
 export interface AddOrUpdateSchemaResponse {
@@ -222,2 +226,3 @@ }
 export interface DeleteSchemaResponse {
+  deletedSchemas: number;
 }
@@ -224,0 +229,0 @@

src/rpcs.ts

@@ -6,2 +6,3 @@ import type {
   DeleteSchemaRequest,
+  DisablePolicyRequest,
   GetPolicyRequest,
@@ -20,2 +21,3 @@ GetSchemaRequest,
   DeleteSchemaResponse,
+  DisablePolicyResponse,
   GetPolicyResponse,
@@ -36,2 +38,3 @@ GetSchemaResponse,
     deleteSchema: [DeleteSchemaRequest, DeleteSchemaResponse];
+    disablePolicy: [DisablePolicyRequest, DisablePolicyResponse];
     getPolicy: [GetPolicyRequest, GetPolicyResponse];
@@ -38,0 +41,0 @@ getSchema: [GetSchemaRequest, GetSchemaResponse];

src/types/external/index.ts

@@ -13,4 +13,7 @@ export * from "./AddOrUpdatePoliciesRequest";
 export * from "./DeleteSchemasRequest";
+export * from "./DeleteSchemasResponse";
 export * from "./DerivedRoleDefinition";
 export * from "./DerivedRoles";
+export * from "./DisablePoliciesRequest";
+export * from "./DisablePoliciesResponse";
 export * from "./Effect";
@@ -17,0 +20,0 @@ export * from "./GetPoliciesRequest";

src/types/external/PolicyBase.ts

@@ -9,7 +9,30 @@ import type { PolicyMetadata } from "./PolicyMetadata";
 export interface PolicyBase {
+  /**
+   * API version of the policy.
+   */
   apiVersion?: string;
+
+  /**
+   * Description of the policy.
+   */
   description?: string;
+
+  /**
+   * Whether the policy is ignored by the Cerbos engine.
+   */
   disabled?: boolean;
+
+  /**
+   * Metadata about the policy.
+   */
   metadata?: PolicyMetadata | undefined;
+
+  /**
+   * Variable expressions defined for the policy.
+   *
+   * @remarks
+   * Each variable is evaluated before any rule condition.
+   * A variable expression can contain anything that condition expression can have.
+   */
   variables?: Record<string, string>;
 }

src/types/external/PolicyMetadata.ts

@@ -7,6 +7,28 @@ /**
 export interface PolicyMetadata {
+  /**
+   * The source of the policy, for auditing purposes.
+   */
   sourceFile: string;
+
+  /**
+   * Free-form data, for auditing purposes.
+   */
   annotations: Record<string, string | undefined>;
+
+  /**
+   * Hash of policy contents.
+   */
   hash: string | undefined;
+
+  /**
+   * Deprecated.
+   *
+   * @deprecated Use {@link PolicyMetadata.storeIdentifier} instead.
+   */
   storeIdentifer: string;
+
+  /**
+   * The policy's identifier in the backend store.
+   */
+  storeIdentifier: string;
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

710269

increased by3.03%

Number of package files

499

increased by3.1%

Lines of code

16814

increased by2.81%

Worsened metrics

Dev dependency count

1

increased byInfinity%

No dependency changes