@cerbos/core - npm Package Compare versions

Comparing version 0.16.0 to 0.17.0

lib/client.d.ts

 /// <reference types="node" />
+import { NotOK } from "./errors";
 import type { _RPC, _Request, _Response, _Service } from "./rpcs";
-import type { AddOrUpdatePoliciesRequest, AddOrUpdateSchemasRequest, CheckResourceRequest, CheckResourcesRequest, CheckResourcesResponse, CheckResourcesResult, DeleteSchemasRequest, DeleteSchemasResponse, DisablePoliciesRequest, DisablePoliciesResponse, EnablePoliciesRequest, EnablePoliciesResponse, GetPoliciesRequest, GetPoliciesResponse, GetSchemasRequest, GetSchemasResponse, IsAllowedRequest, ListPoliciesRequest, ListPoliciesResponse, ListSchemasResponse, PlanResourcesRequest, PlanResourcesResponse, Policy, ReloadStoreRequest, Schema, ServerInfo, ValidationFailedCallback } from "./types/external";
+import type { AddOrUpdatePoliciesRequest, AddOrUpdateSchemasRequest, AuxData, CheckResourceRequest, CheckResourcesRequest, CheckResourcesResponse, CheckResourcesResult, DeleteSchemasRequest, DeleteSchemasResponse, DisablePoliciesRequest, DisablePoliciesResponse, EnablePoliciesRequest, EnablePoliciesResponse, GetPoliciesRequest, GetPoliciesResponse, GetSchemasRequest, GetSchemasResponse, IsAllowedRequest, ListPoliciesRequest, ListPoliciesResponse, ListSchemasResponse, PlanResourcesRequest, PlanResourcesResponse, Policy, Principal, 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>, headers: Headers) => Promise<_Response<Service, RPC>>;
+export declare class _AbortHandler {
+    readonly signal: AbortSignal | undefined;
+    constructor(signal: AbortSignal | undefined);
+    throwIfAborted(): void;
+    onAbort(listener: (error: NotOK) => void): void;
+    private error;
+}
 /** @internal */
+export type _Transport = <Service extends _Service, RPC extends _RPC<Service>>(service: Service, rpc: RPC, request: _Request<Service, RPC>, headers: Headers, abortHandler: _AbortHandler) => Promise<_Response<Service, RPC>>;
+/** @internal */
 export type _Instrumenter = (transport: _Transport) => _Transport;
@@ -103,2 +112,8 @@ /** @internal */
     headers?: HeadersInit | undefined;
+    /**
+     * A {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | signal} to abort the request.
+     *
+     * @defaultValue `undefined`
+     */
+    signal?: AbortSignal | undefined;
 }
@@ -567,2 +582,6 @@ /**
     serverInfo(options?: RequestOptions): Promise<ServerInfo>;
+    /**
+     * Create a client instance with a pre-specified principal.
+     */
+    withPrincipal(principal: Principal, auxData?: Pick<AuxData, "jwt">): ClientWithPrincipal<this>;
     private admin;
@@ -574,2 +593,60 @@ private cerbos;
 }
+/**
+ * A client instance with a pre-specified principal.
+ *
+ * @public
+ */
+export declare class ClientWithPrincipal<ClientType extends Client = Client> {
+    /**
+     * The client from which this instance was created.
+     */
+    readonly client: ClientType;
+    /**
+     * The principal for whom this instance was created.
+     */
+    readonly principal: Principal;
+    /**
+     * Auxiliary data related to the principal for whom this instance was created.
+     *
+     * @defaultValue `{}`
+     */
+    readonly auxData: Pick<AuxData, "jwt">;
+    /** @internal */
+    constructor(
+    /**
+     * The client from which this instance was created.
+     */
+    client: ClientType, 
+    /**
+     * The principal for whom this instance was created.
+     */
+    principal: Principal, 
+    /**
+     * Auxiliary data related to the principal for whom this instance was created.
+     *
+     * @defaultValue `{}`
+     */
+    auxData?: Pick<AuxData, "jwt">);
+    /**
+     * Check the principal's permissions on a resource.
+     * See {@link Client.checkResource} for details.
+     */
+    checkResource(request: Omit<CheckResourceRequest, "principal">, options?: RequestOptions): Promise<CheckResourcesResult>;
+    /**
+     * Check the principal's permissions on a set of resources.
+     * See {@link Client.checkResources} for details.
+     */
+    checkResources(request: Omit<CheckResourcesRequest, "principal">, options?: RequestOptions): Promise<CheckResourcesResponse>;
+    /**
+     * Check if the principal is allowed to perform an action on a resource.
+     * See {@link Client.isAllowed} for details.
+     */
+    isAllowed(request: Omit<IsAllowedRequest, "principal">, options?: RequestOptions): Promise<boolean>;
+    /**
+     * Produce a query plan that can be used to obtain a list of resources on which the principal is allowed to perform a particular action.
+     * See {@link Client.planResources} for details.
+     */
+    planResources(request: Omit<PlanResourcesRequest, "principal">, options?: RequestOptions): Promise<PlanResourcesResponse>;
+    private merge;
+}
 //# sourceMappingURL=client.d.ts.map

lib/client.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = exports._removeInstrumenter = exports._addInstrumenter = void 0;
+exports.ClientWithPrincipal = exports.Client = exports._removeInstrumenter = exports._addInstrumenter = exports._AbortHandler = void 0;
 const fromProtobuf_1 = require("./convert/fromProtobuf");
 const toProtobuf_1 = require("./convert/toProtobuf");
 const errors_1 = require("./errors");
+/** @internal */
+class _AbortHandler {
+    signal;
+    constructor(signal) {
+        this.signal = signal;
+    }
+    throwIfAborted() {
+        if (this.signal?.aborted) {
+            throw this.error();
+        }
+    }
+    onAbort(listener) {
+        this.signal?.addEventListener("abort", () => {
+            listener(this.error());
+        });
+    }
+    error() {
+        const reason = this.signal?.reason;
+        return new errors_1.NotOK(errors_1.Status.CANCELLED, reason instanceof Error ? `Aborted: ${reason.message}` : "Aborted", { cause: reason });
+    }
+}
+exports._AbortHandler = _AbortHandler;
 const instrumenters = new Set();
@@ -547,2 +569,8 @@ /** @internal */
     }
+    /**
+     * Create a client instance with a pre-specified principal.
+     */
+    withPrincipal(principal, auxData = {}) {
+        return new ClientWithPrincipal(this, principal, auxData);
+    }
     async admin(rpc, request, options) {
@@ -554,4 +582,4 @@ return await this.send("admin", rpc, request, this.options.adminCredentials, options);
     }
-    async send(service, rpc, request, adminCredentials, { headers } = {}) {
-        return await this.transport(service, rpc, request, await this.mergeHeaders(headers, adminCredentials));
+    async send(service, rpc, request, adminCredentials, { headers, signal } = {}) {
+        return await this.transport(service, rpc, request, await this.mergeHeaders(headers, adminCredentials), new _AbortHandler(signal));
     }
@@ -587,2 +615,71 @@ async mergeHeaders(override, adminCredentials) {
 exports.Client = Client;
+/**
+ * A client instance with a pre-specified principal.
+ *
+ * @public
+ */
+class ClientWithPrincipal {
+    client;
+    principal;
+    auxData;
+    /** @internal */
+    constructor(
+    /**
+     * The client from which this instance was created.
+     */
+    client, 
+    /**
+     * The principal for whom this instance was created.
+     */
+    principal, 
+    /**
+     * Auxiliary data related to the principal for whom this instance was created.
+     *
+     * @defaultValue `{}`
+     */
+    auxData = {}) {
+        this.client = client;
+        this.principal = principal;
+        this.auxData = auxData;
+    }
+    /**
+     * Check the principal's permissions on a resource.
+     * See {@link Client.checkResource} for details.
+     */
+    async checkResource(request, options) {
+        return await this.client.checkResource(this.merge(request), options);
+    }
+    /**
+     * Check the principal's permissions on a set of resources.
+     * See {@link Client.checkResources} for details.
+     */
+    async checkResources(request, options) {
+        return await this.client.checkResources(this.merge(request), options);
+    }
+    /**
+     * Check if the principal is allowed to perform an action on a resource.
+     * See {@link Client.isAllowed} for details.
+     */
+    async isAllowed(request, options) {
+        return await this.client.isAllowed(this.merge(request), options);
+    }
+    /**
+     * Produce a query plan that can be used to obtain a list of resources on which the principal is allowed to perform a particular action.
+     * See {@link Client.planResources} for details.
+     */
+    async planResources(request, options) {
+        return await this.client.planResources(this.merge(request), options);
+    }
+    merge({ auxData = {}, ...rest }) {
+        return {
+            principal: this.principal,
+            auxData: {
+                ...this.auxData,
+                ...auxData,
+            },
+            ...rest,
+        };
+    }
+}
+exports.ClientWithPrincipal = ClientWithPrincipal;
 //# sourceMappingURL=client.js.map

lib/convert/toProtobuf.js

@@ -267,4 +267,7 @@ "use strict";
 function auxDataToProtobuf({ jwt }) {
+    if (!jwt) {
+        return undefined;
+    }
     return {
-        jwt: jwt && jwtToProtobuf(jwt),
+        jwt: jwtToProtobuf(jwt),
     };
@@ -271,0 +274,0 @@ }

lib/errors.d.ts

@@ -46,2 +46,13 @@ import type { ValidationError } from "./types/external";
 /**
+ * Options for creating an error.
+ *
+ * @public
+ */
+export interface ErrorOptions {
+    /**
+     * The original error that caused this one.
+     */
+    cause?: unknown;
+}
+/**
  * Error thrown when the Cerbos policy decision point server returns an unsuccessful response.
@@ -72,3 +83,3 @@ *
      */
-    details: string);
+    details: string, options?: ErrorOptions);
 }
@@ -91,2 +102,4 @@ /**
 }
+/** @internal */
+export declare function _setErrorNameAndStack(error: Error): void;
 //# sourceMappingURL=errors.d.ts.map

lib/errors.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValidationFailed = exports.NotOK = exports.Status = void 0;
+exports._setErrorNameAndStack = exports.ValidationFailed = exports.NotOK = exports.Status = void 0;
 /**
@@ -76,8 +76,7 @@ * Status codes returned by the Cerbos policy decision point server.
      */
-    details) {
-        super(`gRPC error ${code} (${Status[code]}): ${details}`);
+    details, options) {
+        super(`gRPC error ${code} (${Status[code]}): ${details}`, options);
         this.code = code;
         this.details = details;
-        this.name = this.constructor.name;
-        Error.captureStackTrace(this, this.constructor);
+        _setErrorNameAndStack(this);
     }
@@ -117,7 +116,15 @@ }
         this.validationErrors = validationErrors;
-        this.name = this.constructor.name;
-        Error.captureStackTrace(this, this.constructor);
+        _setErrorNameAndStack(this);
     }
 }
 exports.ValidationFailed = ValidationFailed;
+/** @internal */
+function _setErrorNameAndStack(error) {
+    error.name = error.constructor.name;
+    // `Error.captureStackTrace` is not available in all browsers
+    if ("captureStackTrace" in Error) {
+        Error.captureStackTrace(error, error.constructor);
+    }
+}
+exports._setErrorNameAndStack = _setErrorNameAndStack;
 //# sourceMappingURL=errors.js.map

lib/protobuf/google/protobuf/descriptor.d.ts

@@ -14,23 +14,23 @@ export declare const protobufPackage = "google.protobuf";
 export interface FileOptions {
-    javaPackage: string;
-    javaOuterClassname: string;
-    javaMultipleFiles: boolean;
-    javaGenerateEqualsAndHash: boolean;
-    javaStringCheckUtf8: boolean;
-    optimizeFor: FileOptions_OptimizeMode;
-    goPackage: string;
-    ccGenericServices: boolean;
-    javaGenericServices: boolean;
-    pyGenericServices: boolean;
-    phpGenericServices: boolean;
-    deprecated: boolean;
-    ccEnableArenas: boolean;
-    objcClassPrefix: string;
-    csharpNamespace: string;
-    swiftPrefix: string;
-    phpClassPrefix: string;
-    phpNamespace: string;
-    phpMetadataNamespace: string;
-    rubyPackage: string;
-    features: FeatureSet | undefined;
+    javaPackage?: string | undefined;
+    javaOuterClassname?: string | undefined;
+    javaMultipleFiles?: boolean | undefined;
+    javaGenerateEqualsAndHash?: boolean | undefined;
+    javaStringCheckUtf8?: boolean | undefined;
+    optimizeFor?: FileOptions_OptimizeMode | undefined;
+    goPackage?: string | undefined;
+    ccGenericServices?: boolean | undefined;
+    javaGenericServices?: boolean | undefined;
+    pyGenericServices?: boolean | undefined;
+    phpGenericServices?: boolean | undefined;
+    deprecated?: boolean | undefined;
+    ccEnableArenas?: boolean | undefined;
+    objcClassPrefix?: string | undefined;
+    csharpNamespace?: string | undefined;
+    swiftPrefix?: string | undefined;
+    phpClassPrefix?: string | undefined;
+    phpNamespace?: string | undefined;
+    phpMetadataNamespace?: string | undefined;
+    rubyPackage?: string | undefined;
+    features?: FeatureSet | undefined;
     uninterpretedOption: UninterpretedOption[];
@@ -44,23 +44,23 @@ }
 export interface MessageOptions {
-    messageSetWireFormat: boolean;
-    noStandardDescriptorAccessor: boolean;
-    deprecated: boolean;
-    mapEntry: boolean;
-    deprecatedLegacyJsonFieldConflicts: boolean;
-    features: FeatureSet | undefined;
+    messageSetWireFormat?: boolean | undefined;
+    noStandardDescriptorAccessor?: boolean | undefined;
+    deprecated?: boolean | undefined;
+    mapEntry?: boolean | undefined;
+    deprecatedLegacyJsonFieldConflicts?: boolean | undefined;
+    features?: FeatureSet | undefined;
     uninterpretedOption: UninterpretedOption[];
 }
 export interface FieldOptions {
-    ctype: FieldOptions_CType;
-    packed: boolean;
-    jstype: FieldOptions_JSType;
-    lazy: boolean;
-    unverifiedLazy: boolean;
-    deprecated: boolean;
-    weak: boolean;
-    debugRedact: boolean;
-    retention: FieldOptions_OptionRetention;
+    ctype?: FieldOptions_CType | undefined;
+    packed?: boolean | undefined;
+    jstype?: FieldOptions_JSType | undefined;
+    lazy?: boolean | undefined;
+    unverifiedLazy?: boolean | undefined;
+    deprecated?: boolean | undefined;
+    weak?: boolean | undefined;
+    debugRedact?: boolean | undefined;
+    retention?: FieldOptions_OptionRetention | undefined;
     targets: FieldOptions_OptionTargetType[];
     editionDefaults: FieldOptions_EditionDefault[];
-    features: FeatureSet | undefined;
+    features?: FeatureSet | undefined;
     uninterpretedOption: UninterpretedOption[];
@@ -96,18 +96,18 @@ }
 export interface FieldOptions_EditionDefault {
-    edition: Edition;
-    value: string;
+    edition?: Edition | undefined;
+    value?: string | undefined;
 }
 export interface OneofOptions {
-    features: FeatureSet | undefined;
+    features?: FeatureSet | undefined;
     uninterpretedOption: UninterpretedOption[];
 }
 export interface ServiceOptions {
-    features: FeatureSet | undefined;
-    deprecated: boolean;
+    features?: FeatureSet | undefined;
+    deprecated?: boolean | undefined;
     uninterpretedOption: UninterpretedOption[];
 }
 export interface MethodOptions {
-    deprecated: boolean;
-    idempotencyLevel: MethodOptions_IdempotencyLevel;
-    features: FeatureSet | undefined;
+    deprecated?: boolean | undefined;
+    idempotencyLevel?: MethodOptions_IdempotencyLevel | undefined;
+    features?: FeatureSet | undefined;
     uninterpretedOption: UninterpretedOption[];
@@ -122,8 +122,8 @@ }
     name: UninterpretedOption_NamePart[];
-    identifierValue: string;
-    positiveIntValue: string;
-    negativeIntValue: string;
-    doubleValue: number;
-    stringValue: Uint8Array;
-    aggregateValue: string;
+    identifierValue?: string | undefined;
+    positiveIntValue?: string | undefined;
+    negativeIntValue?: string | undefined;
+    doubleValue?: number | undefined;
+    stringValue?: Uint8Array | undefined;
+    aggregateValue?: string | undefined;
 }
@@ -135,8 +135,8 @@ export interface UninterpretedOption_NamePart {
 export interface FeatureSet {
-    fieldPresence: FeatureSet_FieldPresence;
-    enumType: FeatureSet_EnumType;
-    repeatedFieldEncoding: FeatureSet_RepeatedFieldEncoding;
-    utf8Validation: FeatureSet_Utf8Validation;
-    messageEncoding: FeatureSet_MessageEncoding;
-    jsonFormat: FeatureSet_JsonFormat;
+    fieldPresence?: FeatureSet_FieldPresence | undefined;
+    enumType?: FeatureSet_EnumType | undefined;
+    repeatedFieldEncoding?: FeatureSet_RepeatedFieldEncoding | undefined;
+    utf8Validation?: FeatureSet_Utf8Validation | undefined;
+    messageEncoding?: FeatureSet_MessageEncoding | undefined;
+    jsonFormat?: FeatureSet_JsonFormat | undefined;
 }
@@ -143,0 +143,0 @@ export declare enum FeatureSet_FieldPresence {

lib/types/external/AuxData.d.ts

@@ -11,4 +11,4 @@ import type { JWT } from "./JWT";
      */
-    jwt?: JWT;
+    jwt?: JWT | undefined;
 }
 //# sourceMappingURL=AuxData.d.ts.map

lib/types/external/CheckResourcesRequest.d.ts

@@ -23,3 +23,3 @@ import type { AuxData } from "./AuxData";
      */
-    auxData?: AuxData;
+    auxData?: AuxData | undefined;
     /**
@@ -30,3 +30,3 @@ * Include {@link CheckResourcesResultMetadata | additional metadata} in the results?
      */
-    includeMetadata?: boolean;
+    includeMetadata?: boolean | undefined;
     /**
@@ -37,4 +37,4 @@ * An identifier for tracing the request.
      */
-    requestId?: string;
+    requestId?: string | undefined;
 }
 //# sourceMappingURL=CheckResourcesRequest.d.ts.map

lib/types/external/JWT.d.ts

@@ -17,4 +17,4 @@ /**
      */
-    keySetId?: string;
+    keySetId?: string | undefined;
 }
 //# sourceMappingURL=JWT.d.ts.map

lib/types/external/ListPoliciesRequest.d.ts

@@ -15,3 +15,3 @@ /**
      */
-    includeDisabled?: boolean;
+    includeDisabled?: boolean | undefined;
     /**
@@ -26,3 +26,3 @@ * Only include policies with a name matching the given regular expression.
      */
-    nameRegexp?: string;
+    nameRegexp?: string | undefined;
     /**
@@ -37,3 +37,3 @@ * Only include policies with a scope matching the given regular expression.
      */
-    scopeRegexp?: string;
+    scopeRegexp?: string | undefined;
     /**
@@ -48,4 +48,4 @@ * Only include policies with a version matching the given regular expression.
      */
-    versionRegexp?: string;
+    versionRegexp?: string | undefined;
 }
 //# sourceMappingURL=ListPoliciesRequest.d.ts.map

lib/types/external/Output.d.ts

@@ -14,3 +14,3 @@ import type { OutputExpressions } from "./OutputExpressions";
      */
-    expr?: string;
+    expr?: string | undefined;
     /**
@@ -22,4 +22,4 @@ * {@link https://docs.cerbos.dev/cerbos/latest/policies/conditions | Common Expression Language} expressions to evaluate.
      */
-    when?: OutputExpressions;
+    when?: OutputExpressions | undefined;
 }
 //# sourceMappingURL=Output.d.ts.map

lib/types/external/OutputExpressions.d.ts

@@ -11,3 +11,3 @@ /**
      */
-    ruleActivated?: string;
+    ruleActivated?: string | undefined;
     /**
@@ -17,4 +17,4 @@ * {@link https://docs.cerbos.dev/cerbos/latest/policies/conditions | Common Expression Language} expression to evaluate when the policy rule is partially activated
      */
-    conditionNotMet?: string;
+    conditionNotMet?: string | undefined;
 }
 //# sourceMappingURL=OutputExpressions.d.ts.map

lib/types/external/PlanResourcesRequest.d.ts

@@ -27,3 +27,3 @@ import type { AuxData } from "./AuxData";
      */
-    auxData?: AuxData;
+    auxData?: AuxData | undefined;
     /**
@@ -34,8 +34,10 @@ * Include {@link PlanResourcesMetadata | additional metadata} in the plan?
      */
-    includeMetadata?: boolean;
+    includeMetadata?: boolean | undefined;
     /**
+     * The identifier for tracing the request.
+     *
      * @defaultValue A randomly-generated UUID.
      */
-    requestId?: string;
+    requestId?: string | undefined;
 }
 //# sourceMappingURL=PlanResourcesRequest.d.ts.map

lib/types/external/PolicyBase.d.ts

@@ -11,11 +11,11 @@ import type { PolicyMetadata } from "./PolicyMetadata";
      */
-    apiVersion?: string;
+    apiVersion?: string | undefined;
     /**
      * Description of the policy.
      */
-    description?: string;
+    description?: string | undefined;
     /**
      * Whether the policy is ignored by the Cerbos engine.
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
@@ -34,4 +34,4 @@ * Metadata about the policy.
      */
-    variables?: Record<string, string>;
+    variables?: Record<string, string> | undefined;
 }
 //# sourceMappingURL=PolicyBase.d.ts.map

lib/types/external/Principal.d.ts

@@ -21,3 +21,3 @@ import type { Value } from "./Value";
      */
-    attr?: Record<string, Value>;
+    attr?: Record<string, Value> | undefined;
     /**
@@ -29,3 +29,3 @@ * Application-specific attributes describing the principal (deprecated).
      */
-    attributes?: Record<string, Value>;
+    attributes?: Record<string, Value> | undefined;
     /**
@@ -36,3 +36,3 @@ * The policy version to use when authorizing the principal.
      */
-    policyVersion?: string;
+    policyVersion?: string | undefined;
     /**
@@ -43,4 +43,4 @@ * The {@link https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies | policy scope} to use when authorizing the principal.
      */
-    scope?: string;
+    scope?: string | undefined;
 }
 //# sourceMappingURL=Principal.d.ts.map

lib/types/external/PrincipalPolicyBody.d.ts

@@ -29,3 +29,3 @@ import type { PrincipalRule } from "./PrincipalRule";
      */
-    scope?: string;
+    scope?: string | undefined;
     /**
@@ -32,0 +32,0 @@ * {@link https://docs.cerbos.dev/cerbos/latest/policies/variables | Variables} defined for use in conditions.

lib/types/external/PrincipalRuleAction.d.ts

@@ -28,3 +28,3 @@ import type { Condition } from "./Condition";
      */
-    name?: string;
+    name?: string | undefined;
     /**
@@ -31,0 +31,0 @@ * User-defined output to be produced when evaluating the rule.

lib/types/external/Resource.d.ts

@@ -21,3 +21,3 @@ import type { Value } from "./Value";
      */
-    attr?: Record<string, Value>;
+    attr?: Record<string, Value> | undefined;
     /**
@@ -29,3 +29,3 @@ * Application-specific attributes describing the resource (deprecated).
      */
-    attributes?: Record<string, Value>;
+    attributes?: Record<string, Value> | undefined;
     /**
@@ -36,3 +36,3 @@ * The policy version to use when checking the principal's permissions on the resource.
      */
-    policyVersion?: string;
+    policyVersion?: string | undefined;
     /**
@@ -43,4 +43,4 @@ * The {@link https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies | policy scope} to use when checking the principal's permissions on the resource.
      */
-    scope?: string;
+    scope?: string | undefined;
 }
 //# sourceMappingURL=Resource.d.ts.map

lib/types/external/ResourcePolicyBody.d.ts

@@ -26,3 +26,3 @@ import type { ResourceRule } from "./ResourceRule";
      */
-    importDerivedRoles?: string[];
+    importDerivedRoles?: string[] | undefined;
     /**
@@ -35,3 +35,3 @@ * Rules defining the actions that can be performed on the resource.
      */
-    scope?: string;
+    scope?: string | undefined;
     /**
@@ -38,0 +38,0 @@ * {@link https://docs.cerbos.dev/cerbos/latest/policies/schemas | Schemas} for principal and resource attributes.

lib/types/external/ResourceRule.d.ts

@@ -24,3 +24,3 @@ import type { Condition } from "./Condition";
      */
-    derivedRoles?: string[];
+    derivedRoles?: string[] | undefined;
     /**
@@ -32,3 +32,3 @@ * Static roles to which the rule applies.
      */
-    roles?: string[];
+    roles?: string[] | undefined;
     /**
@@ -41,3 +41,3 @@ * The condition that must be met for the rule to apply.
      */
-    name?: string;
+    name?: string | undefined;
     /**
@@ -44,0 +44,0 @@ * User-defined output to be produced when evaluating the rule.

lib/types/external/Variables.d.ts

@@ -10,8 +10,8 @@ /**
      */
-    import?: string[];
+    import?: string[] | undefined;
     /**
      * Variable expressions defined for the policy.
      */
-    local?: Record<string, string>;
+    local?: Record<string, string> | undefined;
 }
 //# sourceMappingURL=Variables.d.ts.map

package.json

 {
   "name": "@cerbos/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Common types used by the @cerbos/grpc, @cerbos/http, and @cerbos/embedded client libraries",
@@ -19,4 +19,8 @@ "repository": {
   },
-  "main": "./lib/index.js",
-  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
+  },
   "files": [
@@ -29,2 +33,17 @@ "lib/**/*.d.ts",
   ],
+  "keywords": [
+    "Cerbos",
+    "authorization",
+    "access control",
+    "roles",
+    "permissions",
+    "policy",
+    "security",
+    "role-based access control",
+    "RBAC",
+    "attribute-based access control",
+    "ABAC",
+    "policy decision point",
+    "PDP"
+  ],
   "dependencies": {
@@ -35,3 +54,7 @@ "uuid": "^9.0.1"
     "@types/uuid": "9.0.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }

src/client.ts

@@ -24,3 +24,3 @@ import {
 } from "./convert/toProtobuf";
-import { ValidationFailed } from "./errors";
+import { NotOK, Status, ValidationFailed } from "./errors";
 import type { _RPC, _Request, _Response, _Service } from "./rpcs";
@@ -30,2 +30,3 @@ import type {
   AddOrUpdateSchemasRequest,
+  AuxData,
   CheckResourceRequest,
@@ -52,2 +53,3 @@ CheckResourcesRequest,
   Policy,
+  Principal,
   ReloadStoreRequest,
@@ -61,2 +63,29 @@ Schema,
 /** @internal */
+export class _AbortHandler {
+  public constructor(public readonly signal: AbortSignal | undefined) {}
+
+  public throwIfAborted(): void {
+    if (this.signal?.aborted) {
+      throw this.error();
+    }
+  }
+
+  public onAbort(listener: (error: NotOK) => void): void {
+    this.signal?.addEventListener("abort", () => {
+      listener(this.error());
+    });
+  }
+
+  private error(): NotOK {
+    const reason = this.signal?.reason as unknown;
+
+    return new NotOK(
+      Status.CANCELLED,
+      reason instanceof Error ? `Aborted: ${reason.message}` : "Aborted",
+      { cause: reason },
+    );
+  }
+}
+
+/** @internal */
 export type _Transport = <Service extends _Service, RPC extends _RPC<Service>>(
@@ -67,2 +96,3 @@ service: Service,
   headers: Headers,
+  abortHandler: _AbortHandler,
 ) => Promise<_Response<Service, RPC>>;
@@ -187,2 +217,9 @@
   headers?: HeadersInit | undefined;
+
+  /**
+   * A {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | signal} to abort the request.
+   *
+   * @defaultValue `undefined`
+   */
+  signal?: AbortSignal | undefined;
 }
@@ -882,2 +919,12 @@
 
+  /**
+   * Create a client instance with a pre-specified principal.
+   */
+  public withPrincipal(
+    principal: Principal,
+    auxData: Pick<AuxData, "jwt"> = {},
+  ): ClientWithPrincipal<this> {
+    return new ClientWithPrincipal(this, principal, auxData);
+  }
+
   private async admin<RPC extends _RPC<"admin">>(
@@ -910,3 +957,3 @@ rpc: RPC,
     adminCredentials: AdminCredentials | undefined,
-    { headers }: RequestOptions = {},
+    { headers, signal }: RequestOptions = {},
   ): Promise<_Response<Service, RPC>> {
@@ -918,2 +965,3 @@ return await this.transport(
       await this.mergeHeaders(headers, adminCredentials),
+      new _AbortHandler(signal),
     );
@@ -972,1 +1020,85 @@ }
 }
+
+/**
+ * A client instance with a pre-specified principal.
+ *
+ * @public
+ */
+export class ClientWithPrincipal<ClientType extends Client = Client> {
+  /** @internal */
+  public constructor(
+    /**
+     * The client from which this instance was created.
+     */
+    public readonly client: ClientType,
+
+    /**
+     * The principal for whom this instance was created.
+     */
+    public readonly principal: Principal,
+
+    /**
+     * Auxiliary data related to the principal for whom this instance was created.
+     *
+     * @defaultValue `{}`
+     */
+    public readonly auxData: Pick<AuxData, "jwt"> = {},
+  ) {}
+
+  /**
+   * Check the principal's permissions on a resource.
+   * See {@link Client.checkResource} for details.
+   */
+  public async checkResource(
+    request: Omit<CheckResourceRequest, "principal">,
+    options?: RequestOptions,
+  ): Promise<CheckResourcesResult> {
+    return await this.client.checkResource(this.merge(request), options);
+  }
+
+  /**
+   * Check the principal's permissions on a set of resources.
+   * See {@link Client.checkResources} for details.
+   */
+  public async checkResources(
+    request: Omit<CheckResourcesRequest, "principal">,
+    options?: RequestOptions,
+  ): Promise<CheckResourcesResponse> {
+    return await this.client.checkResources(this.merge(request), options);
+  }
+
+  /**
+   * Check if the principal is allowed to perform an action on a resource.
+   * See {@link Client.isAllowed} for details.
+   */
+  public async isAllowed(
+    request: Omit<IsAllowedRequest, "principal">,
+    options?: RequestOptions,
+  ): Promise<boolean> {
+    return await this.client.isAllowed(this.merge(request), options);
+  }
+
+  /**
+   * Produce a query plan that can be used to obtain a list of resources on which the principal is allowed to perform a particular action.
+   * See {@link Client.planResources} for details.
+   */
+  public async planResources(
+    request: Omit<PlanResourcesRequest, "principal">,
+    options?: RequestOptions,
+  ): Promise<PlanResourcesResponse> {
+    return await this.client.planResources(this.merge(request), options);
+  }
+
+  private merge<
+    Request extends { principal: Principal; auxData?: AuxData | undefined },
+  >({ auxData = {}, ...rest }: Omit<Request, "principal">): Request {
+    return {
+      principal: this.principal,
+      auxData: {
+        ...this.auxData,
+        ...auxData,
+      },
+      ...rest,
+    } as Request;
+  }
+}

src/convert/toProtobuf.ts

@@ -475,5 +475,9 @@ import { v4 as uuidv4 } from "uuid";
 
-function auxDataToProtobuf({ jwt }: AuxData): AuxDataProtobuf {
+function auxDataToProtobuf({ jwt }: AuxData): AuxDataProtobuf | undefined {
+  if (!jwt) {
+    return undefined;
+  }
+
   return {
-    jwt: jwt && jwtToProtobuf(jwt),
+    jwt: jwtToProtobuf(jwt),
   };
@@ -480,0 +484,0 @@ }

src/errors.ts

@@ -56,2 +56,14 @@ import type { ValidationError } from "./types/external";
 /**
+ * Options for creating an error.
+ *
+ * @public
+ */
+export interface ErrorOptions {
+  /**
+   * The original error that caused this one.
+   */
+  cause?: unknown;
+}
+
+/**
  * Error thrown when the Cerbos policy decision point server returns an unsuccessful response.
@@ -84,6 +96,7 @@ *
     public readonly details: string,
+
+    options?: ErrorOptions,
   ) {
-    super(`gRPC error ${code} (${Status[code]}): ${details}`);
-    this.name = this.constructor.name;
-    Error.captureStackTrace(this, this.constructor);
+    super(`gRPC error ${code} (${Status[code]}): ${details}`, options);
+    _setErrorNameAndStack(this);
   }
@@ -132,5 +145,14 @@ }
     super("Input failed schema validation");
-    this.name = this.constructor.name;
-    Error.captureStackTrace(this, this.constructor);
+    _setErrorNameAndStack(this);
   }
 }
+
+/** @internal */
+export function _setErrorNameAndStack(error: Error): void {
+  error.name = error.constructor.name;
+
+  // `Error.captureStackTrace` is not available in all browsers
+  if ("captureStackTrace" in Error) {
+    Error.captureStackTrace(error, error.constructor);
+  }
+}

src/protobuf/google/protobuf/descriptor.ts

@@ -18,23 +18,23 @@ /* eslint-disable */
 export interface FileOptions {
-  javaPackage: string;
-  javaOuterClassname: string;
-  javaMultipleFiles: boolean;
-  javaGenerateEqualsAndHash: boolean;
-  javaStringCheckUtf8: boolean;
-  optimizeFor: FileOptions_OptimizeMode;
-  goPackage: string;
-  ccGenericServices: boolean;
-  javaGenericServices: boolean;
-  pyGenericServices: boolean;
-  phpGenericServices: boolean;
-  deprecated: boolean;
-  ccEnableArenas: boolean;
-  objcClassPrefix: string;
-  csharpNamespace: string;
-  swiftPrefix: string;
-  phpClassPrefix: string;
-  phpNamespace: string;
-  phpMetadataNamespace: string;
-  rubyPackage: string;
-  features: FeatureSet | undefined;
+  javaPackage?: string | undefined;
+  javaOuterClassname?: string | undefined;
+  javaMultipleFiles?: boolean | undefined;
+  javaGenerateEqualsAndHash?: boolean | undefined;
+  javaStringCheckUtf8?: boolean | undefined;
+  optimizeFor?: FileOptions_OptimizeMode | undefined;
+  goPackage?: string | undefined;
+  ccGenericServices?: boolean | undefined;
+  javaGenericServices?: boolean | undefined;
+  pyGenericServices?: boolean | undefined;
+  phpGenericServices?: boolean | undefined;
+  deprecated?: boolean | undefined;
+  ccEnableArenas?: boolean | undefined;
+  objcClassPrefix?: string | undefined;
+  csharpNamespace?: string | undefined;
+  swiftPrefix?: string | undefined;
+  phpClassPrefix?: string | undefined;
+  phpNamespace?: string | undefined;
+  phpMetadataNamespace?: string | undefined;
+  rubyPackage?: string | undefined;
+  features?: FeatureSet | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -50,8 +50,8 @@ }
 export interface MessageOptions {
-  messageSetWireFormat: boolean;
-  noStandardDescriptorAccessor: boolean;
-  deprecated: boolean;
-  mapEntry: boolean;
-  deprecatedLegacyJsonFieldConflicts: boolean;
-  features: FeatureSet | undefined;
+  messageSetWireFormat?: boolean | undefined;
+  noStandardDescriptorAccessor?: boolean | undefined;
+  deprecated?: boolean | undefined;
+  mapEntry?: boolean | undefined;
+  deprecatedLegacyJsonFieldConflicts?: boolean | undefined;
+  features?: FeatureSet | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -61,14 +61,14 @@ }
 export interface FieldOptions {
-  ctype: FieldOptions_CType;
-  packed: boolean;
-  jstype: FieldOptions_JSType;
-  lazy: boolean;
-  unverifiedLazy: boolean;
-  deprecated: boolean;
-  weak: boolean;
-  debugRedact: boolean;
-  retention: FieldOptions_OptionRetention;
+  ctype?: FieldOptions_CType | undefined;
+  packed?: boolean | undefined;
+  jstype?: FieldOptions_JSType | undefined;
+  lazy?: boolean | undefined;
+  unverifiedLazy?: boolean | undefined;
+  deprecated?: boolean | undefined;
+  weak?: boolean | undefined;
+  debugRedact?: boolean | undefined;
+  retention?: FieldOptions_OptionRetention | undefined;
   targets: FieldOptions_OptionTargetType[];
   editionDefaults: FieldOptions_EditionDefault[];
-  features: FeatureSet | undefined;
+  features?: FeatureSet | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -109,8 +109,8 @@ }
 export interface FieldOptions_EditionDefault {
-  edition: Edition;
-  value: string;
+  edition?: Edition | undefined;
+  value?: string | undefined;
 }
 
 export interface OneofOptions {
-  features: FeatureSet | undefined;
+  features?: FeatureSet | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -120,4 +120,4 @@ }
 export interface ServiceOptions {
-  features: FeatureSet | undefined;
-  deprecated: boolean;
+  features?: FeatureSet | undefined;
+  deprecated?: boolean | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -127,5 +127,5 @@ }
 export interface MethodOptions {
-  deprecated: boolean;
-  idempotencyLevel: MethodOptions_IdempotencyLevel;
-  features: FeatureSet | undefined;
+  deprecated?: boolean | undefined;
+  idempotencyLevel?: MethodOptions_IdempotencyLevel | undefined;
+  features?: FeatureSet | undefined;
   uninterpretedOption: UninterpretedOption[];
@@ -142,8 +142,8 @@ }
   name: UninterpretedOption_NamePart[];
-  identifierValue: string;
-  positiveIntValue: string;
-  negativeIntValue: string;
-  doubleValue: number;
-  stringValue: Uint8Array;
-  aggregateValue: string;
+  identifierValue?: string | undefined;
+  positiveIntValue?: string | undefined;
+  negativeIntValue?: string | undefined;
+  doubleValue?: number | undefined;
+  stringValue?: Uint8Array | undefined;
+  aggregateValue?: string | undefined;
 }
@@ -157,8 +157,8 @@
 export interface FeatureSet {
-  fieldPresence: FeatureSet_FieldPresence;
-  enumType: FeatureSet_EnumType;
-  repeatedFieldEncoding: FeatureSet_RepeatedFieldEncoding;
-  utf8Validation: FeatureSet_Utf8Validation;
-  messageEncoding: FeatureSet_MessageEncoding;
-  jsonFormat: FeatureSet_JsonFormat;
+  fieldPresence?: FeatureSet_FieldPresence | undefined;
+  enumType?: FeatureSet_EnumType | undefined;
+  repeatedFieldEncoding?: FeatureSet_RepeatedFieldEncoding | undefined;
+  utf8Validation?: FeatureSet_Utf8Validation | undefined;
+  messageEncoding?: FeatureSet_MessageEncoding | undefined;
+  jsonFormat?: FeatureSet_JsonFormat | undefined;
 }
@@ -165,0 +165,0 @@

src/types/external/AuxData.ts

@@ -12,3 +12,3 @@ import type { JWT } from "./JWT";
    */
-  jwt?: JWT;
+  jwt?: JWT | undefined;
 }

src/types/external/CheckResourcesRequest.ts

@@ -26,3 +26,3 @@ import type { AuxData } from "./AuxData";
    */
-  auxData?: AuxData;
+  auxData?: AuxData | undefined;
 
@@ -34,3 +34,3 @@ /**
    */
-  includeMetadata?: boolean;
+  includeMetadata?: boolean | undefined;
 
@@ -42,3 +42,3 @@ /**
    */
-  requestId?: string;
+  requestId?: string | undefined;
 }

src/types/external/JWT.ts

@@ -18,3 +18,3 @@ /**
    */
-  keySetId?: string;
+  keySetId?: string | undefined;
 }

src/types/external/ListPoliciesRequest.ts

@@ -15,3 +15,3 @@ /**
    */
-  includeDisabled?: boolean;
+  includeDisabled?: boolean | undefined;
 
@@ -27,3 +27,3 @@ /**
    */
-  nameRegexp?: string;
+  nameRegexp?: string | undefined;
 
@@ -39,3 +39,3 @@ /**
    */
-  scopeRegexp?: string;
+  scopeRegexp?: string | undefined;
 
@@ -51,3 +51,3 @@ /**
    */
-  versionRegexp?: string;
+  versionRegexp?: string | undefined;
 }

src/types/external/Output.ts

@@ -15,3 +15,3 @@ import type { OutputExpressions } from "./OutputExpressions";
    */
-  expr?: string;
+  expr?: string | undefined;
 
@@ -24,3 +24,3 @@ /**
    */
-  when?: OutputExpressions;
+  when?: OutputExpressions | undefined;
 }

src/types/external/OutputExpressions.ts

@@ -11,3 +11,3 @@ /**
    */
-  ruleActivated?: string;
+  ruleActivated?: string | undefined;
 
@@ -18,3 +18,3 @@ /**
    */
-  conditionNotMet?: string;
+  conditionNotMet?: string | undefined;
 }

src/types/external/PlanResourcesRequest.ts

@@ -31,3 +31,3 @@ import type { AuxData } from "./AuxData";
    */
-  auxData?: AuxData;
+  auxData?: AuxData | undefined;
 
@@ -39,8 +39,10 @@ /**
    */
-  includeMetadata?: boolean;
+  includeMetadata?: boolean | undefined;
 
   /**
+   * The identifier for tracing the request.
+   *
    * @defaultValue A randomly-generated UUID.
    */
-  requestId?: string;
+  requestId?: string | undefined;
 }

src/types/external/PolicyBase.ts

@@ -12,3 +12,3 @@ import type { PolicyMetadata } from "./PolicyMetadata";
    */
-  apiVersion?: string;
+  apiVersion?: string | undefined;
 
@@ -18,3 +18,3 @@ /**
    */
-  description?: string;
+  description?: string | undefined;
 
@@ -24,3 +24,3 @@ /**
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
 
@@ -41,3 +41,3 @@ /**
    */
-  variables?: Record<string, string>;
+  variables?: Record<string, string> | undefined;
 }

src/types/external/Principal.ts

@@ -24,3 +24,3 @@ import type { Value } from "./Value";
    */
-  attr?: Record<string, Value>;
+  attr?: Record<string, Value> | undefined;
 
@@ -33,3 +33,3 @@ /**
    */
-  attributes?: Record<string, Value>;
+  attributes?: Record<string, Value> | undefined;
 
@@ -41,3 +41,3 @@ /**
    */
-  policyVersion?: string;
+  policyVersion?: string | undefined;
 
@@ -49,3 +49,3 @@ /**
    */
-  scope?: string;
+  scope?: string | undefined;
 }

src/types/external/PrincipalPolicyBody.ts

@@ -33,3 +33,3 @@ import type { PrincipalRule } from "./PrincipalRule";
    */
-  scope?: string;
+  scope?: string | undefined;
 
@@ -36,0 +36,0 @@ /**

src/types/external/PrincipalRuleAction.ts

@@ -32,3 +32,3 @@ import type { Condition } from "./Condition";
    */
-  name?: string;
+  name?: string | undefined;
 
@@ -35,0 +35,0 @@ /**

src/types/external/Resource.ts

@@ -24,3 +24,3 @@ import type { Value } from "./Value";
    */
-  attr?: Record<string, Value>;
+  attr?: Record<string, Value> | undefined;
 
@@ -33,3 +33,3 @@ /**
    */
-  attributes?: Record<string, Value>;
+  attributes?: Record<string, Value> | undefined;
 
@@ -41,3 +41,3 @@ /**
    */
-  policyVersion?: string;
+  policyVersion?: string | undefined;
 
@@ -49,3 +49,3 @@ /**
    */
-  scope?: string;
+  scope?: string | undefined;
 }

src/types/external/ResourcePolicyBody.ts

@@ -29,3 +29,3 @@ import type { ResourceRule } from "./ResourceRule";
    */
-  importDerivedRoles?: string[];
+  importDerivedRoles?: string[] | undefined;
 
@@ -40,3 +40,3 @@ /**
    */
-  scope?: string;
+  scope?: string | undefined;
 
@@ -43,0 +43,0 @@ /**

src/types/external/ResourceRule.ts

@@ -27,3 +27,3 @@ import type { Condition } from "./Condition";
    */
-  derivedRoles?: string[];
+  derivedRoles?: string[] | undefined;
 
@@ -36,3 +36,3 @@ /**
    */
-  roles?: string[];
+  roles?: string[] | undefined;
 
@@ -47,3 +47,3 @@ /**
    */
-  name?: string;
+  name?: string | undefined;
 
@@ -50,0 +50,0 @@ /**

src/types/external/Variables.ts

@@ -10,3 +10,3 @@ /**
    */
-  import?: string[];
+  import?: string[] | undefined;
 
@@ -16,3 +16,3 @@ /**
    */
-  local?: Record<string, string>;
+  local?: Record<string, string> | undefined;
 }

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

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

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

519465

increased by3.52%

Lines of code

12093

increased by2.88%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes