Cerbos JavaScript SDK
    Preparing search index...

    Class GRPC

    A client for interacting with the Cerbos policy decision point server over gRPC.

    Not supported in browsers.

    See the parent class for available methods.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    addOrUpdatePolicies addOrUpdateSchemas checkHealth checkResource checkResources close deleteSchema deleteSchemas disablePolicies disablePolicy enablePolicies enablePolicy getAccessLogEntry getDecisionLogEntry getPolicies getPolicy getSchema getSchemas inspectPolicies isAllowed listAccessLogEntries listDecisionLogEntries listPolicies listSchemas planResources reloadStore serverInfo withPrincipal

    Constructors

    • Create a client for interacting with the Cerbos policy decision point (PDP) server over gRPC.

      Parameters

      • target: string

        Cerbos PDP server address ("host", "host:port", or "unix:/path/to/socket").

      • options: Options

        Additional client settings.

      Returns GRPC

      Connect via TCP with no encryption:

      const cerbos = new GRPC("localhost:3593", { tls: false });

      Connect via a Unix socket with no encryption:

      const cerbos = new GRPC("unix:/var/run/cerbos.grpc.sock", { tls: false });

      Connect to the hosted demo PDP to experiment in the playground:

      const cerbos = new GRPC("demo-pdp.cerbos.cloud", { tls: true, playgroundInstance: "gE623b0180QlsG5a4QIN6UOZ6f3iSFW2" });

    Methods

    • Add policies, or update existing policies.

      Parameters

      Returns Promise<void>

      Requires

      Create a policy in code:

      await cerbos.addOrUpdatePolicies({
        policies: [{
          resourcePolicy: {
            resource: "document",
            version: "1",
            rules: [{
              actions: ["*"],
              effect: Effect.ALLOW,
              roles: ["ADMIN"],
            }],
          },
        }],
      });

      Load a policy from a YAML or JSON file with readPolicy:

      import { readPolicy } from "@cerbos/files";

      await cerbos.addOrUpdatePolicies({
        policies: [await readPolicy("path/to/policy.yaml")],
      });

      Load policies and schemas from a directory with readDirectory:

      import { readDirectory } from "@cerbos/files";

      const { policies, schemas } = await readDirectory("path/to/directory");

      await cerbos.addOrUpdateSchemas({ schemas });
      await cerbos.addOrUpdatePolicies({ policies });

    • Add schemas to be used for validating principal or resource attributes, or update existing schemas.

      Parameters

      Returns Promise<void>

      Requires

      Create a schema in code:

      await cerbos.addOrUpdateSchemas({
        schemas: [{
          id: "document.json",
          definition: {
            type: "object",
            properties: {
              owner: { type: "string" }
            }
          },
        }],
      });

      Load a schema from a JSON file with readSchema:

      import { readSchema } from "@cerbos/files";

      await cerbos.addOrUpdateSchemas({
        schemas: [await readSchema("_schemas/path/to/schema.json")],
      });

      Load policies and schemas from a directory with readDirectory:

      import { readDirectory } from "@cerbos/files";

      const { policies, schemas } = await readDirectory("path/to/directory");

      await cerbos.addOrUpdateSchemas({ schemas });
      await cerbos.addOrUpdatePolicies({ policies });

    • Check a principal's permissions on a set of resources.

      Parameters

      Returns Promise<CheckResourcesResponse>

      const decision = await cerbos.checkResources({
        principal: {
          id: "user@example.com",
          roles: ["USER"],
          attr: { tier: "PREMIUM" },
        },
        resources: [
          {
            resource: {
              kind: "document",
              id: "1",
              attr: { owner: "user@example.com" },
            },
            actions: ["view", "edit"],
          },
          {
            resource: {
              kind: "image",
              id: "1",
              attr: { owner: "user@example.com" },
            },
            actions: ["delete"],
          },
        ],
      });

      decision.isAllowed({
        resource: { kind: "document", id: "1" },
        action: "view",
      }); // => true

    • Disconnect from the Cerbos policy decision point server and clean up resources.

      Returns void

      It is safe to call close more than once.

      Any interactions with the server after calling close will throw an error.

    • Delete a schema.

      Parameters

      Returns Promise<boolean>

      Requires

      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.

      const deleted = await cerbos.deleteSchema("document.json");

    • Check if a principal is allowed to perform an action on a resource.

      Parameters

      Returns Promise<boolean>

      await cerbos.isAllowed({
        principal: {
          id: "user@example.com",
          roles: ["USER"],
          attr: { tier: "PREMIUM" },
        },
        resource: {
          kind: "document",
          id: "1",
          attr: { owner: "user@example.com" },
        },
        action: "view",
      }); // => true

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods