diff --git a/packages/solid/src/resource/Resource.ts b/packages/solid/src/resource/Resource.ts index 2c34788..41bcb51 100644 --- a/packages/solid/src/resource/Resource.ts +++ b/packages/solid/src/resource/Resource.ts @@ -536,6 +536,12 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ * =========================================================================== */ + /** + * Retrieves the URI for the web access control (WAC) rules for this resource + * @param options - set the "ignoreCache" field to true to ignore any cached + * information on WAC rules. + * @returns WAC Rules results + */ protected async getWacUri(options?: { ignoreCache: boolean; }): Promise { @@ -559,6 +565,34 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ return wacUriResult; } + /** + * Retrieves web access control (WAC) rules for this resource + * @param options - set the "ignoreCache" field to true to ignore any cached + * information on WAC rules. + * @returns WAC Rules results + * + * @example + * ```typescript + * const resource = ldoSolidDataset + * .getResource("https://example.com/container/resource.ttl"); + * const wacRulesResult = await resource.getWac(); + * if (!wacRulesResult.isError) { + * const wacRules = wacRulesResult.wacRule; + * // True if the resource is publicly readable + * console.log(wacRules.public.read); + * // True if authenticated agents can write to the resource + * console.log(wacRules.authenticated.write); + * // True if the given WebId has append access + * console.log( + * wacRules.agent[https://example.com/person1/profile/card#me].append + * ); + * // True if the given WebId has control access + * console.log( + * wacRules.agent[https://example.com/person1/profile/card#me].control + * ); + * } + * ``` + */ async getWac(options?: { ignoreCache: boolean; }): Promise { @@ -599,12 +633,53 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ return parentResource.getWac(); } + /** + * Sets access rules for a specific resource + * @param wacRule - the access rules to set + * @returns SetWacRuleResult + * + * @example + * ```typescript + * const resource = ldoSolidDataset + * .getResource("https://example.com/container/resource.ttl"); + * const wacRulesResult = await resource.setWac({ + * public: { + * read: true, + * write: false, + * append: false, + * control: false + * }, + * authenticated: { + * read: true, + * write: false, + * append: true, + * control: false + * }, + * agent: { + * "https://example.com/person1/profile/card#me": { + * read: true, + * write: true, + * append: true, + * control: true + * } + * } + * }); + * ``` + */ async setWac(wacRule: WacRule): Promise { const wacUriResult = await this.getWacUri(); if (wacUriResult.isError) return wacUriResult; - return setWacRuleForAclUri(wacUriResult.wacUri, wacRule, this.uri, { - fetch: this.context.fetch, - }); + const result = await setWacRuleForAclUri( + wacUriResult.wacUri, + wacRule, + this.uri, + { + fetch: this.context.fetch, + }, + ); + if (result.isError) return result; + this.wacRule = result.wacRule; + return result; } } diff --git a/packages/solid/src/resource/wac/WacRule.ts b/packages/solid/src/resource/wac/WacRule.ts index 1edc67d..150ed52 100644 --- a/packages/solid/src/resource/wac/WacRule.ts +++ b/packages/solid/src/resource/wac/WacRule.ts @@ -1,3 +1,6 @@ +/** + * A list of modes that a certain agent has access to + */ export interface AccessModeList { read: boolean; append: boolean; @@ -5,6 +8,9 @@ export interface AccessModeList { control: boolean; } +/** + * A list of modes for each kind of agent + */ export interface WacRule { public: AccessModeList; authenticated: AccessModeList; diff --git a/packages/solid/src/resource/wac/getWacRule.ts b/packages/solid/src/resource/wac/getWacRule.ts index 0171ef3..3c2b68f 100644 --- a/packages/solid/src/resource/wac/getWacRule.ts +++ b/packages/solid/src/resource/wac/getWacRule.ts @@ -20,6 +20,12 @@ export type GetWacRuleResult = | GetWacRuleError | WacRuleAbsent; +/** + * Given the URI of an ACL document, return the Web Access Control (WAC) rules + * @param aclUri: The URI for the ACL document + * @param options: Options object to include an authenticated fetch function + * @returns GetWacRuleResult + */ export async function getWacRuleWithAclUri( aclUri: string, options?: BasicRequestOptions, diff --git a/packages/solid/src/resource/wac/getWacUri.ts b/packages/solid/src/resource/wac/getWacUri.ts index e21668c..d402c8b 100644 --- a/packages/solid/src/resource/wac/getWacUri.ts +++ b/packages/solid/src/resource/wac/getWacUri.ts @@ -18,6 +18,12 @@ export type GetWacUriError = | UnexpectedResourceError; export type GetWacUriResult = GetWacUriSuccess | GetWacUriError; +/** + * Get the URI for the WAC rules of a specific resource + * @param resourceUri: the URI of the resource + * @param options: Options object to include an authenticated fetch function + * @returns GetWacUriResult + */ export async function getWacUri( resourceUri: string, options?: BasicRequestOptions, diff --git a/packages/solid/src/resource/wac/results/GetWacRuleSuccess.ts b/packages/solid/src/resource/wac/results/GetWacRuleSuccess.ts index 1b472c4..4dd17b6 100644 --- a/packages/solid/src/resource/wac/results/GetWacRuleSuccess.ts +++ b/packages/solid/src/resource/wac/results/GetWacRuleSuccess.ts @@ -1,7 +1,13 @@ import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult"; import type { WacRule } from "../WacRule"; +/** + * Returned when a WAC rule is successfully retrieved + */ export interface GetWacRuleSuccess extends ResourceSuccess { type: "getWacRuleSuccess"; + /** + * The rule that was retrieved + */ wacRule: WacRule; } diff --git a/packages/solid/src/resource/wac/results/GetWacUriSuccess.ts b/packages/solid/src/resource/wac/results/GetWacUriSuccess.ts index b819946..3694d9f 100644 --- a/packages/solid/src/resource/wac/results/GetWacUriSuccess.ts +++ b/packages/solid/src/resource/wac/results/GetWacUriSuccess.ts @@ -1,7 +1,13 @@ import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult"; import type { LeafUri } from "../../../util/uriTypes"; +/** + * Returned when the URI for a resources ACL document was successfully retried + */ export interface GetWacUriSuccess extends ResourceSuccess { type: "getWacUriSuccess"; + /** + * The URI of the ACL document + */ wacUri: LeafUri; } diff --git a/packages/solid/src/resource/wac/results/SetWacRuleSuccess.ts b/packages/solid/src/resource/wac/results/SetWacRuleSuccess.ts index 303f941..a79b928 100644 --- a/packages/solid/src/resource/wac/results/SetWacRuleSuccess.ts +++ b/packages/solid/src/resource/wac/results/SetWacRuleSuccess.ts @@ -1,7 +1,13 @@ import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult"; import type { WacRule } from "../WacRule"; +/** + * Returned when rules were successfully written + */ export interface SetWacRuleSuccess extends ResourceSuccess { type: "setWacRuleSuccess"; + /** + * The written rule + */ wacRule: WacRule; } diff --git a/packages/solid/src/resource/wac/results/WacRuleAbsent.ts b/packages/solid/src/resource/wac/results/WacRuleAbsent.ts index 739ad2e..7bec46a 100644 --- a/packages/solid/src/resource/wac/results/WacRuleAbsent.ts +++ b/packages/solid/src/resource/wac/results/WacRuleAbsent.ts @@ -1,5 +1,8 @@ import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult"; +/** + * Returned if no WAC rule was returned from the server + */ export interface WacRuleAbsent extends ResourceSuccess { type: "wacRuleAbsent"; } diff --git a/packages/solid/src/resource/wac/setWacRule.ts b/packages/solid/src/resource/wac/setWacRule.ts index 2495eb3..adbac93 100644 --- a/packages/solid/src/resource/wac/setWacRule.ts +++ b/packages/solid/src/resource/wac/setWacRule.ts @@ -16,6 +16,15 @@ import { guaranteeFetch } from "../../util/guaranteeFetch"; export type SetWacRuleError = HttpErrorResultType | UnexpectedResourceError; export type SetWacRuleResult = SetWacRuleSuccess | SetWacRuleError; +/** + * Given the URI of an ACL document and some WAC rules, set the WAC rules of + * that document + * @param aclUri: The URI for the ACL document + * @param newRule: A new WAC rule to set. This will overwrite old rules + * @param accessTo: The document this rule refers to + * @param options: Options object to include an authenticated fetch function + * @returns SetWacRuleResult + */ export async function setWacRuleForAclUri( aclUri: LeafUri, newRule: WacRule,