Class Client`Abstract`

Base implementation of a client for interacting with the Cerbos policy decision point server.

Hierarchy (View Summary)

Client

Methods

addOrUpdatePolicies

addOrUpdatePolicies(
request: AddOrUpdatePoliciesRequest,
options?: RequestOptions,
): Promise<void>

Add policies, or update existing policies.

Parameters

request: AddOrUpdatePoliciesRequest
Optionaloptions: RequestOptions

Returns Promise<void>

Remarks

Requires

the client to be configured with Options.adminCredentials,
the Cerbos policy decision point server to be configured with the admin API enabled, and
a dynamic storage backend.

Example

Create a policy in code:

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

Example

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")],
});

Example

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 });

addOrUpdateSchemas

addOrUpdateSchemas(
request: AddOrUpdateSchemasRequest,
options?: RequestOptions,
): Promise<void>
Add schemas to be used for validating principal or resource attributes, or update existing schemas.
Parameters
- request: AddOrUpdateSchemasRequest
- Optionaloptions: RequestOptions
Returns Promise<void>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be configured with the admin API enabled, and
- a dynamic storage backend.
Example
Create a schema in code:
```
await cerbos.addOrUpdateSchemas({
  schemas: [{
    id: "document.json",
    definition: {
      type: "object",
      properties: {
        owner: { type: "string" }
      }
    },
  }],
});
```
Example
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")],
});
```
Example
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 });
```
- Defined in packages/core/src/client.ts:325

checkHealth

checkHealth(
request?: HealthCheckRequest,
options?: RequestOptions,
): Promise<HealthCheckResponse>
Checks the health of services provided by the policy decision point server.
Parameters
- request: HealthCheckRequest = {}
- Optionaloptions: RequestOptions
Returns Promise<HealthCheckResponse>
Example
```
const { status } = await cerbos.checkHealth();
```
Example
```
const { status } = await cerbos.checkHealth({ service: Service.ADMIN });
```
- Defined in packages/core/src/client.ts:349

checkResource

checkResource(
request: CheckResourceRequest,
options?: RequestOptions,
): Promise<CheckResourcesResult>

Check a principal's permissions on a resource.

Parameters

request: CheckResourceRequest
Optionaloptions: RequestOptions

Returns Promise<CheckResourcesResult>

Example

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

decision.isAllowed("view"); // => true

checkResources

checkResources(
request: CheckResourcesRequest,
options?: RequestOptions,
): Promise<CheckResourcesResponse>

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

Parameters

request: CheckResourcesRequest
Optionaloptions: RequestOptions

Returns Promise<CheckResourcesResponse>

Example

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

deleteSchema

deleteSchema(id: string, options?: RequestOptions): Promise<boolean>
Delete a schema.
Parameters
- id: string
- Optionaloptions: RequestOptions
Returns Promise<boolean>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point (PDP) server to be configured with the admin API enabled, and
- a dynamic 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
```
const deleted = await cerbos.deleteSchema("document.json");
```
- Defined in packages/core/src/client.ts:490

deleteSchemas

deleteSchemas(
request: DeleteSchemasRequest,
options?: RequestOptions,
): Promise<DeleteSchemasResponse>
Delete multiple schemas.
Parameters
- request: DeleteSchemasRequest
- Optionaloptions: RequestOptions
Returns Promise<DeleteSchemasResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point (PDP) server to be configured with the admin API enabled, and
- a dynamic 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 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
```
const result = await cerbos.deleteSchemas({
  ids: ["document.json", "image.json"],
});
```
- Defined in packages/core/src/client.ts:521

disablePolicies

disablePolicies(
request: DisablePoliciesRequest,
options?: RequestOptions,
): Promise<DisablePoliciesResponse>
Disable multiple policies.
Parameters
- request: DisablePoliciesRequest
- Optionaloptions: RequestOptions
Returns Promise<DisablePoliciesResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be at least v0.25 and configured with the admin API enabled, and
- a dynamic storage backend.
Example
```
const result = await cerbos.disablePolicies({
  ids: ["resource.document.v1", "resource.image.v1"],
});
```
- Defined in packages/core/src/client.ts:553

disablePolicy

disablePolicy(id: string, options?: RequestOptions): Promise<boolean>
Disable a policy.
Parameters
- id: string
- Optionaloptions: RequestOptions
Returns Promise<boolean>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be at least v0.25 and configured with the admin API enabled, and
- a dynamic storage backend.
Example
```
const disabled = await cerbos.disablePolicy("resource.document.v1");
```
- Defined in packages/core/src/client.ts:583

enablePolicies

enablePolicies(
request: EnablePoliciesRequest,
options?: RequestOptions,
): Promise<EnablePoliciesResponse>
Enable multiple policies.
Parameters
- request: EnablePoliciesRequest
- Optionaloptions: RequestOptions
Returns Promise<EnablePoliciesResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be at least v0.26 and configured with the admin API enabled, and
- a dynamic storage backend.
Example
```
const result = await cerbos.enablePolicies({
  ids: ["resource.document.v1", "resource.image.v1"],
});
```
- Defined in packages/core/src/client.ts:614

enablePolicy

enablePolicy(id: string, options?: RequestOptions): Promise<boolean>
Enable a policy.
Parameters
- id: string
- Optionaloptions: RequestOptions
Returns Promise<boolean>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be at least v0.26 and configured with the admin API enabled, and
- a dynamic storage backend.
Example
```
const enabled = await cerbos.enablePolicy("resource.document.v1");
```
- Defined in packages/core/src/client.ts:644

getAccessLogEntry

getAccessLogEntry(
callId: string,
options?: RequestOptions,
): Promise<AccessLogEntry | undefined>
Fetch an access log entry by call ID from the policy decision point server's audit log.
Parameters
- callId: string
- Optionaloptions: RequestOptions
Returns Promise<AccessLogEntry | undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials; and
- the Cerbos policy decision point server to be configured with
  
  the admin API enabled
  
  the local audit logging backend, and
  
  access logs enabled.
Example
```
const entry = await cerbos.getAccessLogEntry("01F9VS1N77S83MTSBBX44GYSJ6");
```
- Defined in packages/core/src/client.ts:677

getDecisionLogEntry

getDecisionLogEntry(
callId: string,
options?: RequestOptions,
): Promise<DecisionLogEntry | undefined>
Fetch a decision log entry by call ID from the policy decision point server's audit log.
Parameters
- callId: string
- Optionaloptions: RequestOptions
Returns Promise<DecisionLogEntry | undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials; and
- the Cerbos policy decision point server to be at least v0.18 and configured with
  
  the admin API enabled
  
  the local audit logging backend, and
  
  decision logs enabled.
Example
```
const entry = await cerbos.getDecisionLogEntry("01F9VS1N77S83MTSBBX44GYSJ6");
```
- Defined in packages/core/src/client.ts:717

getPolicies

getPolicies(
request: GetPoliciesRequest,
options?: RequestOptions,
): Promise<GetPoliciesResponse>
Fetch multiple policies by ID.
Parameters
- request: GetPoliciesRequest
- Optionaloptions: RequestOptions
Returns Promise<GetPoliciesResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const policies = await cerbos.getPolicies({
  ids: ["resource.document.v1", "resource.image.v1"],
});
```
- Defined in packages/core/src/client.ts:753

getPolicy

getPolicy(id: string, options?: RequestOptions): Promise<Policy | undefined>
Fetch a policy by ID.
Parameters
- id: string
- Optionaloptions: RequestOptions
Returns Promise<Policy | undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const policy = await cerbos.getPolicy("resource.document.v1");
```
- Defined in packages/core/src/client.ts:781

getSchema

getSchema(id: string, options?: RequestOptions): Promise<Schema | undefined>
Fetch a schema by ID.
Parameters
- id: string
- Optionaloptions: RequestOptions
Returns Promise<Schema | undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const schema = await cerbos.getSchema("document.json");
```
- Defined in packages/core/src/client.ts:807

getSchemas

getSchemas(
request: GetSchemasRequest,
options?: RequestOptions,
): Promise<GetSchemasResponse>
Fetch multiple schemas by ID.
Parameters
- request: GetSchemasRequest
- Optionaloptions: RequestOptions
Returns Promise<GetSchemasResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const schemas = await cerbos.getSchemas({
  ids: ["document.json", "image.json"],
});
```
- Defined in packages/core/src/client.ts:835

inspectPolicies

inspectPolicies(
request?: InspectPoliciesRequest,
options?: RequestOptions,
): Promise<InspectPoliciesResponse>
Inspect policies in the store.
Parameters
- request: InspectPoliciesRequest = {}
- Optionaloptions: RequestOptions
Returns Promise<InspectPoliciesResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials; and
- the Cerbos policy decision point server to be at least v0.35 and configured with the admin API enabled.
Example
```
const { policies } = await cerbos.inspectPolicies();
```
- Defined in packages/core/src/client.ts:863

isAllowed

isAllowed(request: IsAllowedRequest, options?: RequestOptions): Promise<boolean>

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

Parameters

request: IsAllowedRequest
Optionaloptions: RequestOptions

Returns Promise<boolean>

Example

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

listAccessLogEntries

listAccessLogEntries(
request: ListAccessLogEntriesRequest,
options?: RequestOptions,
): AsyncGenerator<AccessLogEntry, void, undefined>
List access log entries from the policy decision point server's audit log.
Parameters
- request: ListAccessLogEntriesRequest
- Optionaloptions: RequestOptions
Returns AsyncGenerator<AccessLogEntry, void, undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials; and
- the Cerbos policy decision point server to be configured with
  
  the admin API enabled
  
  the local audit logging backend, and
  
  access logs enabled.
Example
```
for await (const entry of cerbos.listAccessLogEntries({ filter: { tail: 5 } })) {
  console.log(entry);
}
```
- Defined in packages/core/src/client.ts:937

listDecisionLogEntries

listDecisionLogEntries(
request: ListDecisionLogEntriesRequest,
options?: RequestOptions,
): AsyncGenerator<DecisionLogEntry, void, undefined>
List decision log entries from the policy decision point server's audit log.
Parameters
- request: ListDecisionLogEntriesRequest
- Optionaloptions: RequestOptions
Returns AsyncGenerator<DecisionLogEntry, void, undefined>
Remarks
Requires
- the client to be configured with Options.adminCredentials; and
- the Cerbos policy decision point server to be configured with
  
  the admin API enabled
  
  the local audit logging backend, and
  
  decision logs enabled.
Example
```
for await (const entry of cerbos.listDecisionLogEntries({ filter: { tail: 5 } })) {
  console.log(entry);
}
```
- Defined in packages/core/src/client.ts:973

listPolicies

listPolicies(
request?: ListPoliciesRequest,
options?: RequestOptions,
): Promise<ListPoliciesResponse>
List policies.
Parameters
- request: ListPoliciesRequest = {}
- Optionaloptions: RequestOptions
Returns Promise<ListPoliciesResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const { ids } = await cerbos.listPolicies();
```
- Defined in packages/core/src/client.ts:1001

listSchemas

listSchemas(options?: RequestOptions): Promise<ListSchemasResponse>
List schemas.
Parameters
- Optionaloptions: RequestOptions
Returns Promise<ListSchemasResponse>
Remarks
Requires
- the client to be configured with Options.adminCredentials, and
- the Cerbos policy decision point server to be configured with the admin API enabled.
Example
```
const { ids } = await cerbos.listSchemas();
```
- Defined in packages/core/src/client.ts:1029

planResources

planResources(
request: PlanResourcesRequest,
options?: RequestOptions,
): Promise<PlanResourcesResponse>
Produce a query plan that can be used to obtain a list of resources on which a principal is allowed to perform a particular action.
Parameters
- request: PlanResourcesRequest
- Optionaloptions: RequestOptions
Returns Promise<PlanResourcesResponse>
Example
```
const plan = await cerbos.planResources({
  principal: {
    id: "user@example.com",
    roles: ["USER"],
    attr: { tier: "PREMIUM" },
  },
  resource: { kind: "document" },
  action: "view",
});
```
- Defined in packages/core/src/client.ts:1057

reloadStore

reloadStore(
request: ReloadStoreRequest,
options?: RequestOptions,
): Promise<void>
Reload the store.
Parameters
- request: ReloadStoreRequest
- Optionaloptions: RequestOptions
Returns Promise<void>
Remarks
Requires
- the client to be configured with Options.adminCredentials,
- the Cerbos policy decision point server to be configured with the admin API, and
- a reloadable storage backend.
Example
```
await cerbos.reloadStore({ wait: true });
```
- Defined in packages/core/src/client.ts:1091

serverInfo

serverInfo(options?: RequestOptions): Promise<ServerInfo>
Retrieve information about the Cerbos policy decision point server.
Parameters
- Optionaloptions: RequestOptions
Returns Promise<ServerInfo>
- Defined in packages/core/src/client.ts:1105

withPrincipal

withPrincipal(
principal: Principal,
auxData?: Pick<AuxData, "jwt">,
): ClientWithPrincipal<Client>
Create a client instance with a pre-specified principal.
Parameters
- principal: Principal
- auxData: Pick<AuxData, "jwt"> = {}
Returns ClientWithPrincipal<Client>
- Defined in packages/core/src/client.ts:1118

Class ClientAbstract

Hierarchy (View Summary)

Index

Methods

Methods

addOrUpdatePolicies

Parameters

Returns Promise<void>

Remarks

Example

Example

Example

addOrUpdateSchemas

Parameters

Returns Promise<void>

Remarks

Example

Example

Example

checkHealth

Parameters

Returns Promise<HealthCheckResponse>

Example

Example

checkResource

Parameters

Returns Promise<CheckResourcesResult>

Example

checkResources

Parameters

Returns Promise<CheckResourcesResponse>

Example

deleteSchema

Parameters

Returns Promise<boolean>

Remarks

Example

deleteSchemas

Parameters

Returns Promise<DeleteSchemasResponse>

Remarks

Example

disablePolicies

Parameters

Returns Promise<DisablePoliciesResponse>

Remarks

Example

disablePolicy

Parameters

Returns Promise<boolean>

Remarks

Example

enablePolicies

Parameters

Returns Promise<EnablePoliciesResponse>

Remarks

Example

enablePolicy

Parameters

Returns Promise<boolean>

Remarks

Example

getAccessLogEntry

Parameters

Returns Promise<AccessLogEntry | undefined>

Remarks

Example

getDecisionLogEntry

Parameters

Returns Promise<DecisionLogEntry | undefined>

Remarks

Example

getPolicies

Parameters

Returns Promise<GetPoliciesResponse>

Remarks

Example

getPolicy

Parameters

Returns Promise<Policy | undefined>

Class Client`Abstract`