Class Embedded

A client for interacting with an embedded Cerbos policy decision point (PDP).

Remarks

Embedded PDP bundles are WebAssembly modules downloaded from Cerbos Hub. Bundle download URLs are available in the "Embedded" section of the "Decision points" page of your Cerbos Hub workspace.

See the parent class for available methods.

Hierarchy (View Summary)

Client
- Embedded

Constructors

constructor

new Embedded(loader: Loader): Embedded
Create a client for interacting with an embedded Cerbos policy decision point (PDP), using a specified Loader to load the embedded PDP bundle.
Parameters
- loader: Loader
Returns Embedded
Remarks
Bundle download URLs are available in the "Embedded" section of the "Decision points" page of your Cerbos Hub workspace.
Example
Fetch an embedded PDP bundle via HTTP in a supported browser or Node.js, and automatically update the bundle when newer versions become available:
```
const loader = new AutoUpdatingLoader("https://lite.cerbos.cloud/bundle?workspace=...&label=...");
const cerbos = new Embedded(loader);
```
Overrides Client.constructor
- Defined in packages/embedded/src/client.ts:36
new Embedded(source: Source, options?: Options): Embedded
Create a client for interacting with an embedded Cerbos policy decision point (PDP), using the default Loader to load the embedded PDP bundle.
Parameters
- source: Source
  WebAssembly binary code of an embedded PDP bundle, or a URL or HTTP response from which to stream it.
- Optionaloptions: Options
  Additional settings.
Returns Embedded
Remarks
This is equivalent to new Embedded(new Loader(source, options)).

Bundle download URLs are available in the "Embedded" section of the "Decision points" page of your Cerbos Hub workspace.
Example
Fetch an embedded PDP bundle via HTTP in a supported browser or Node.js:
```
const cerbos = new Embedded("https://lite.cerbos.cloud/bundle?workspace=...&label=...");
```
Overrides Client.constructor
- Defined in packages/embedded/src/client.ts:56

Properties

`Readonly`loader

loader: Loader

The Loader used to load the embedded policy decision point bundle.

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 });
```
Inherited from Client.addOrUpdateSchemas
- Defined in packages/core/lib/client.d.ts:208

checkHealth

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

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");
```
Inherited from Client.deleteSchema
- Defined in packages/core/lib/client.d.ts:305

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"],
});
```
Inherited from Client.deleteSchemas
- Defined in packages/core/lib/client.d.ts:329

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"],
});
```
Inherited from Client.disablePolicies
- Defined in packages/core/lib/client.d.ts:349

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");
```
Inherited from Client.disablePolicy
- Defined in packages/core/lib/client.d.ts:367

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"],
});
```
Inherited from Client.enablePolicies
- Defined in packages/core/lib/client.d.ts:387

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");
```
Inherited from Client.enablePolicy
- Defined in packages/core/lib/client.d.ts:405

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");
```
Inherited from Client.getAccessLogEntry
- Defined in packages/core/lib/client.d.ts:427

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");
```
Inherited from Client.getDecisionLogEntry
- Defined in packages/core/lib/client.d.ts:449

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"],
});
```
Inherited from Client.getPolicies
- Defined in packages/core/lib/client.d.ts:467

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");
```
Inherited from Client.getPolicy
- Defined in packages/core/lib/client.d.ts:483

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");
```
Inherited from Client.getSchema
- Defined in packages/core/lib/client.d.ts:499

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"],
});
```
Inherited from Client.getSchemas
- Defined in packages/core/lib/client.d.ts:517

inspectPolicies

inspectPolicies(
request?: InspectPoliciesRequest,
options?: RequestOptions,
): Promise<InspectPoliciesResponse>
Inspect policies in the store.
Parameters
- Optionalrequest: 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();
```
Inherited from Client.inspectPolicies
- Defined in packages/core/lib/client.d.ts:533

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
```
Inherited from Client.isAllowed
- Defined in packages/core/lib/client.d.ts:554

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);
}
```
Inherited from Client.listAccessLogEntries
- Defined in packages/core/lib/client.d.ts:578

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);
}
```
Inherited from Client.listDecisionLogEntries
- Defined in packages/core/lib/client.d.ts:602

listPolicies

listPolicies(
request?: ListPoliciesRequest,
options?: RequestOptions,
): Promise<ListPoliciesResponse>
List policies.
Parameters
- Optionalrequest: 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();
```
Inherited from Client.listPolicies
- Defined in packages/core/lib/client.d.ts:618

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();
```
Inherited from Client.listSchemas
- Defined in packages/core/lib/client.d.ts:634

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",
});
```
Inherited from Client.planResources
- Defined in packages/core/lib/client.d.ts:651

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 });
```
Inherited from Client.reloadStore
- Defined in packages/core/lib/client.d.ts:669

serverInfo

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

withPrincipal

withPrincipal(
principal: Principal,
auxData?: Pick<AuxData, "jwt">,
): ClientWithPrincipal<Embedded>
Create a client instance with a pre-specified principal.
Parameters
- principal: Principal
- OptionalauxData: Pick<AuxData, "jwt">
Returns ClientWithPrincipal<Embedded>
Inherited from Client.withPrincipal
- Defined in packages/core/lib/client.d.ts:677

Class Embedded

Remarks

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Embedded

Remarks

Example

Parameters

Returns Embedded

Remarks

Example

Properties

Readonlyloader

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>

`Readonly`loader