Module: acl/acl#

Type Aliases#

Access#

Ƭ Access: Object

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:428

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:414

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
`ResourceExt`	extends `WithServerResourceInfo` = `WithServerResourceInfo`

Defined in#

src/acl/acl.ts:487

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
`ResourceExt`	extends `WithAcl` = `WithAcl`

Defined in#

src/acl/acl.ts:474

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
`ResourceExt`	extends `WithAcl` = `WithAcl`

Defined in#

src/acl/acl.ts:461

Functions#

createAcl#

▸ createAcl(targetResource): 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` & {} & { `internal_resourceInfo`: { `aclUrl`: `string` } }	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:274

createAclFromFallbackAcl#

▸ createAclFromFallbackAcl(resource): 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`	`WithAcl` & { `internal_acl`: { `fallbackAcl`: `AclDataset` } } & `WithResourceInfo` & {} & { `internal_resourceInfo`: { `aclUrl`: `string` } }	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:303

deleteAclFor#

▸ deleteAclFor<Resource>(resource, options?): 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`	extends `WithResourceInfo` & {} & { `internal_resourceInfo`: { `aclUrl`: `string` } }

Parameters#

Name	Type	Description
`resource`	`Resource`	The Resource for which you want to delete the ACL.
`options?`	`Object`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

Returns#

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

Defined in#

src/acl/acl.ts:378

getFallbackAcl#

▸ getFallbackAcl(resource): 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`<`WithAcl`>	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:255

▸ getFallbackAcl(dataset): AclDataset | null

Parameters#

Name	Type
`dataset`	`WithAcl`

Returns#

AclDataset | null

Defined in#

src/acl/acl.ts:256

getFileWithAcl#

▸ getFileWithAcl(input, options?): 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.

Parameters#

Name	Type	Description
`input`	`string` \| `Url`	-
`options?`	`Object`	Fetching options: a custom fetcher and/or headers.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

Returns#

Promise<File & WithServerResourceInfo & WithAcl>

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

Since

0.2.0

Defined in#

src/acl/acl.ts:148

getResourceAcl#

▸ getResourceAcl(resource): 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` & `WithResourceInfo` & {} & { `internal_acl`: { `resourceAcl`: `AclDataset` } }	A Resource with potentially an ACL attached.

Returns#

AclDataset

The resource ACL if available and null if not.

Defined in#

src/acl/acl.ts:197

▸ getResourceAcl(resource): AclDataset | null

Parameters#

Name	Type
`resource`	`WithAcl` & `WithResourceInfo` & {}

Returns#

AclDataset | null

Defined in#

src/acl/acl.ts:200

getResourceInfoWithAcl#

▸ getResourceInfoWithAcl(url, options?): 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	Description
`url`	`string`	URL of the SolidDataset to fetch.
`options?`	`Object`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

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:174

getSolidDatasetWithAcl#

▸ getSolidDatasetWithAcl(url, options?): 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	Description
`url`	`string` \| `Url`	URL of the SolidDataset to fetch.
`options?`	`Object`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

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:115

hasAccessibleAcl#

▸ hasAccessibleAcl<ResourceExt>(dataset): 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`	extends `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:510

hasAcl#

▸ hasAcl<T>(dataset): 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`	extends `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:61

hasFallbackAcl#

▸ hasFallbackAcl<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`	extends `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:234

hasResourceAcl#

▸ hasResourceAcl<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`	extends `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:82

saveAclFor#

▸ saveAclFor(resource, resourceAcl, options?): 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	Description
`resource`	`WithAccessibleAcl`<`WithServerResourceInfo`>	The Resource to which the given resource ACL applies.
`resourceAcl`	`Readonly`<{}>	An [[AclDataset]] whose ACL Rules will apply to `resource`.
`options?`	`Object`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

Returns#

Promise<AclDataset & WithResourceInfo>

Defined in#

src/acl/acl.ts:340