@inrupt/solid-client / acl/acl

Module: acl/acl

Type aliases

Access

Ƭ Access: { append: boolean ; control: boolean ; read: boolean ; write: boolean }

An object with the boolean properties read, append, write and control, representing the respective Access Modes defined by the Web Access Control specification.

Since that specification is not finalised yet, this interface is still experimental.

Type declaration:

Name

Type

append

boolean

control

boolean

read

boolean

write

boolean

Defined in: src/acl/acl.ts:440


AclDataset

Ƭ AclDataset: SolidDataset & WithResourceInfo & { internal_accessTo: UrlString }

A SolidDataset containing Access Control rules for another SolidDataset.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Defined in: src/acl/acl.ts:426


WithAccessibleAcl

Ƭ WithAccessibleAcl<ResourceExt>: ResourceExt & { internal_resourceInfo: { aclUrl: Exclude<WithServerResourceInfo[internal_resourceInfo][aclUrl], undefined> } }

If this type applies to a Resource, its Access Control List, if it exists, is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters:

Name

Type

Default

ResourceExt

WithServerResourceInfo

WithServerResourceInfo

Defined in: src/acl/acl.ts:501


WithFallbackAcl

Ƭ WithFallbackAcl<ResourceExt>: ResourceExt & { internal_acl: { fallbackAcl: Exclude<WithAcl[internal_acl][fallbackAcl], null> } }

If this type applies to a Resource, the Access Control List that applies to its nearest Container with an ACL is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters:

Name

Type

Default

ResourceExt

WithAcl

WithAcl

Defined in: src/acl/acl.ts:487


WithResourceAcl

Ƭ WithResourceAcl<ResourceExt>: ResourceExt & { internal_acl: { resourceAcl: Exclude<WithAcl[internal_acl][resourceAcl], null> } }

If this type applies to a Resource, an Access Control List that applies to it exists and is accessible to the currently authenticated user.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters:

Name

Type

Default

ResourceExt

WithAcl

WithAcl

Defined in: src/acl/acl.ts:473

Functions

createAcl

createAcl(targetResource: WithResourceInfo & WithAccessibleAcl): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Creates an empty resource ACL (Access Control List) for a given Resource.

Parameters:

Name

Type

Description

targetResource

WithResourceInfo & WithAccessibleAcl

A Resource that does not have its own ACL yet (see hasResourceAcl).

Returns: AclDataset

An empty resource ACL for the given Resource.

Defined in: src/acl/acl.ts:279


createAclFromFallbackAcl

createAclFromFallbackAcl(resource: WithFallbackAcl & WithResourceInfo & WithAccessibleAcl): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Creates a resource ACL (Access Control List), initialised from the fallback ACL inherited from the given Resource’s Container (or another of its ancestor Containers). That is, the new ACL has the same rules/entries as the fallback ACL that currently applies to the Resource.

Parameters:

Name

Type

Description

resource

WithFallbackAcl & WithResourceInfo & WithAccessibleAcl

A Resource without its own resource ACL (see hasResourceAcl) but with an accessible fallback ACL (see hasFallbackAcl).

Returns: AclDataset

A resource ACL initialised with the rules/entries from the Resource’s fallback ACL.

Defined in: src/acl/acl.ts:307


deleteAclFor

deleteAclFor<Resource>(resource: Resource, options?: Partial<typeof internal_defaultFetchOptions>): Promise<Resource & { acl: { resourceAcl: null } }>

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Removes the resource ACL (Access Control List) from a Resource.

Once the resource ACL is removed from the Resource, the Resource relies on the fallback ACL inherited from the Resource’s parent Container (or another of its ancestor Containers).

Type parameters:

Name

Type

Resource

WithAccessibleAcl<WithServerResourceInfo>

Parameters:

Name

Type

Default value

Description

resource

Resource

-

The Resource for which you want to delete the ACL.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns: Promise<Resource & { acl: { resourceAcl: null } }>

Defined in: src/acl/acl.ts:386


getFallbackAcl

getFallbackAcl(resource: WithFallbackAcl): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Returns the fallback ACL (Access Control List) attached to a Resource.

If the Resource has a fallback ACL attached and is accessible by the user (see hasFallbackAcl), the function returns the fallback ACL. If the Resource does not hava a fallback ACL attached or is inaccessible by the user, the function returns null.

Parameters:

Name

Type

Description

resource

WithFallbackAcl

A Resource with potentially a fallback ACL attached.

Returns: AclDataset

The fallback ACL if available or null if not.

Defined in: src/acl/acl.ts:260

getFallbackAcl(dataset: WithAcl): AclDataset | null

Parameters:

Name

Type

dataset

WithAcl

Returns: AclDataset | null

Defined in: src/acl/acl.ts:261


getFileWithAcl

getFileWithAcl(input: Url | UrlString, options?: Partial<typeof internal_defaultFetchOptions>): Promise<File & WithServerResourceInfo & WithAcl>

Note

This function is still experimental and subject to change, even in a non-major release.

Retrieves a file, its resource ACL (Access Control List) if available, and its fallback ACL from a URL and returns them as a blob.

If the user calling the function does not have access to the file’s resource ACL, hasAccessibleAcl on the returned blob returns false. If the user has access to the file’s resource ACL but the resource ACL does not exist, getResourceAcl on the returned blob returns null. If the fallback ACL is inaccessible by the user, getFallbackAcl on the returned blob returns null.

Tip

To retrieve the ACLs, the function results in multiple HTTP requests rather than a single request as mandated by the Solid spec. As such, prefer getFile instead if you do not need the ACL.

since 0.2.0

Parameters:

Name

Type

Default value

Description

input

Url | UrlString

-

-

options

Partial<typeof internal_defaultFetchOptions>

Fetching options: a custom fetcher and/or headers.

Returns: Promise<File & WithServerResourceInfo & WithAcl>

A file and its ACLs, if available to the authenticated user, as a blob.

Defined in: src/acl/acl.ts:149


getResourceAcl

getResourceAcl(resource: WithAcl & WithServerResourceInfo & WithResourceAcl): AclDataset

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Returns the resource ACL (Access Control List) attached to a Resource.

If the Resource has its resource ACL attached and is accessible by the user (see hasResourceAcl), the function returns the resource ACL. If the Resource does not have a resource ACL attached or is inaccessible by the user, the function returns null.

Parameters:

Name

Type

Description

resource

WithAcl & WithServerResourceInfo & WithResourceAcl

A Resource with potentially an ACL attached.

Returns: AclDataset

The resource ACL if available and null if not.

Defined in: src/acl/acl.ts:202

getResourceAcl(resource: WithAcl & WithServerResourceInfo): AclDataset | null

Parameters:

Name

Type

resource

WithAcl & WithServerResourceInfo

Returns: AclDataset | null

Defined in: src/acl/acl.ts:205


getResourceInfoWithAcl

getResourceInfoWithAcl(url: UrlString, options?: Partial<typeof internal_defaultFetchOptions>): Promise<WithServerResourceInfo & WithAcl>

Experimental: fetch a Resource’s metadata and its associated Access Control List.

This is an experimental function that fetches both a Resource’s metadata, the linked ACL Resource (if available), and the ACL that applies to it if the linked ACL Resource is not available (if accessible). This can result in many HTTP requests being executed, in lieu of the Solid spec mandating servers to provide this info in a single request.

If the Resource’s linked ACL Resource could not be fetched (because it does not exist, or because the authenticated user does not have access to it), acl.resourceAcl will be null. If the applicable Container’s ACL is not accessible to the authenticated user, acl.fallbackAcl will be null.

Parameters:

Name

Type

Default value

Description

url

UrlString

-

URL of the SolidDataset to fetch.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns: Promise<WithServerResourceInfo & WithAcl>

A Resource’s metadata and the ACLs that apply to the Resource, if available to the authenticated user.

Defined in: src/acl/acl.ts:177


getSolidDatasetWithAcl

getSolidDatasetWithAcl(url: UrlString | Url, options?: Partial<typeof internal_defaultFetchOptions>): Promise<SolidDataset & WithServerResourceInfo & WithAcl>

Experimental: fetch a SolidDataset and its associated Access Control List.

This is an experimental function that fetches both a Resource, the linked ACL Resource (if available), and the ACL that applies to it if the linked ACL Resource is not available. This can result in many HTTP requests being executed, in lieu of the Solid spec mandating servers to provide this info in a single request. Therefore, and because this function is still experimental, prefer getSolidDataset instead.

If the Resource does not advertise the ACL Resource (because the authenticated user does not have access to it), the acl property in the returned value will be null. acl.resourceAcl will be undefined if the Resource’s linked ACL Resource could not be fetched (because it does not exist), and acl.fallbackAcl will be null if the applicable Container’s ACL is not accessible to the authenticated user.

Parameters:

Name

Type

Default value

Description

url

UrlString | Url

-

URL of the SolidDataset to fetch.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns: Promise<SolidDataset & WithServerResourceInfo & WithAcl>

A SolidDataset and the ACLs that apply to it, if available to the authenticated user.

Defined in: src/acl/acl.ts:114


hasAccessibleAcl

hasAccessibleAcl<ResourceExt>(dataset: ResourceExt): dataset is WithAccessibleAcl<ResourceExt>

Given a SolidDataset, verify whether its Access Control List is accessible to the current user.

This should generally only be true for SolidDatasets fetched by getSolidDatasetWithAcl.

Please note that the Web Access Control specification is not yet finalised, and hence, this function is still experimental and can change in a non-major release.

Type parameters:

Name

Type

ResourceExt

WithServerResourceInfo

Parameters:

Name

Type

Description

dataset

ResourceExt

A SolidDataset.

Returns: dataset is WithAccessibleAcl<ResourceExt>

Whether the given dataset has a an ACL that is accessible to the current user.

Defined in: src/acl/acl.ts:524


hasAcl

hasAcl<T>(dataset: T): dataset is T & WithAcl

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verify whether a given SolidDataset was fetched together with its Access Control List.

Type parameters:

Name

Type

T

object

Parameters:

Name

Type

Description

dataset

T

A SolidDataset that may have its ACLs attached.

Returns: dataset is T & WithAcl

True if dataset was fetched together with its ACLs.

Defined in: src/acl/acl.ts:60


hasFallbackAcl

hasFallbackAcl<Resource>(resource: Resource): resource is Resource & WithAcl & object

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verifies whether the given Resource has a fallback ACL (Access Control List) attached.

A fallback ACL for a Resource is inherited from the Resource’s parent Container (or another of its ancestor Containers) and applies if the Resource does not have its own resource ACL.

The hasFallbackAcl function checks that:

  • a given Resource has a fallback ACL attached, and

  • the user calling hasFallbackAcl has Control access to the Container from which the Resource inherits its ACL.

To retrieve a Resource with its ACLs, see getSolidDatasetWithAcl.

Type parameters:

Name

Type

Resource

WithAcl

Parameters:

Name

Type

Description

resource

Resource

A SolidDataset that might have a fallback ACL attached.

Returns: resource is Resource & WithAcl & object

true if the Resource has a fallback ACL attached that is accessible to the user.

Defined in: src/acl/acl.ts:239


hasResourceAcl

hasResourceAcl<Resource>(resource: Resource): resource is Resource & WithAcl & object & WithResourceInfo & object & object

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Verifies whether the given Resource has a resource ACL (Access Control List) attached.

The hasResourceAcl function checks that:

  • a given Resource has a resource ACL attached, and

  • the user calling hasResourceAcl has Control access to the Resource.

To retrieve a Resource with its ACLs, see getSolidDatasetWithAcl.

Type parameters:

Name

Type

Resource

WithAcl & WithResourceInfo & { }

Parameters:

Name

Type

Description

resource

Resource

A Resource that might have an ACL attached.

Returns: resource is Resource & WithAcl & object & WithResourceInfo & object & object

true if the Resource has a resource ACL attached that is accessible by the user.

Defined in: src/acl/acl.ts:81


saveAclFor

saveAclFor(resource: WithAccessibleAcl, resourceAcl: AclDataset, options?: Partial<typeof internal_defaultFetchOptions>): Promise<AclDataset & WithResourceInfo>

Note

The Web Access Control specification is not yet finalised. As such, this function is still experimental and subject to change, even in a non-major release.

Saves the resource ACL for a Resource.

Parameters:

Name

Type

Default value

Description

resource

WithAccessibleAcl

-

The Resource to which the given resource ACL applies.

resourceAcl

AclDataset

-

An AclDataset whose ACL Rules will apply to resource.

options

Partial<typeof internal_defaultFetchOptions>

Optional parameter options.fetch: An alternative fetch function to make the HTTP request, compatible with the browser-native fetch API.

Returns: Promise<AclDataset & WithResourceInfo>

Defined in: src/acl/acl.ts:344