Access Control Policy (ACP)

3.1.1. Example Context

The following example context graph denotes instances of resource access initiated by Bob.

[]
  a acp:Context ;
  acp:agent ex:Bob .  

The following example context graph means that Bob requests access to resource X using client application Y and with their identity asserted by identity provider Z; furthermore, resource X was created by Alice and is owned by Bob.

ex:contextA
  acp:target ex:resourceX ;
  acp:agent ex:Bob ;
  acp:client ex:ClientApplicationY ;  
  acp:issuer ex:IdentityProviderZ ;
  acp:owner ex:Bob ;
  acp:creator ex:Alice .

The following example context graph denotes instances of resource access where client application X or client application Y are used and identity is asserted by identity provider Z.

[
  acp:client ex:ClientApplicationX, ex:ClientApplicationY ;  
  acp:issuer ex:IdentityProviderZ ;
] .

3.2.1. Example Context extension

Let's imagine a property ex:tag defined as a an rdfs:subPropertyOf acp:attribute that would describe tags applied to requested resources. If such a property was defined, then the following example context graph would denote instances of resource access over resource X initiated by Bob where resource X was tagged ex:Music and ex:FavouriteRecord.

ex:contextA
  acp:target ex:resourceX ;
  acp:agent ex:Bob ;
  ex:tag ex:Music, ex:FavouriteRecord .  

4.1.1. Example Access Control Resource

The following example authorization graph means that access to resource X is controlled by both Access Controls B and C; furthermore, access to members of resource X is controlled by Access Control D; furthermore, member control is transitive, therefore, further members of member resources will also be controlled by Access Control D.

ex:accessControlResourceA
  acp:resource ex:resourceX ;
  acp:accessControl ex:accessControlB, ex:accessControlC ;  
  acp:memberAccessControl ex:accessControlD .

4.2.1. Example Access Control

The following example authorization graph means that access to resource X is controlled by Policy C.

ex:accessControlResourceA
  acp:resource ex:resourceX ;  
  acp:accessControl [
    acp:apply ex:policyC ;
  ] .

The following two example authorization graphs both mean that access to resource X is controlled by Policy D and Policy E.

ex:accessControlResourceA
  acp:resource ex:resourceX ;
  acp:accessControl ex:accessControlB, ex:accessControlC .  

ex:accessControlB
  acp:apply ex:policyD .

ex:accessControlC
  acp:apply ex:policyE .

[]
  acp:resource ex:resourceX ;
  acp:accessControl ex:accessControlF .  

ex:accessControlF
  acp:apply ex:policyD, ex:policyE .

4.3.1. Example Policy

The following example authorization graph means that Policy A will allow acl:Read for instances of resource access satisfying both Matcher B and Matcher C.

ex:policyA
  acp:allow acl:Read ;
  acp:allOf ex:matcherB, ex:matcherC .  

The following example authorization graph means that a Policy will deny acl:Write for instances of resource access satisfying either Matcher B or Matcher C.

[]
  acp:deny acl:Write ;
  acp:anyOf ex:matcherB, ex:matcherC .  

The following example authorization graph means that reading and writing resource X will be allowed for instances of resource access satisfying Matcher A and not Matcher B.

[
  acp:resource ex:resourceX ;
  acp:accessControl [
    acp:apply [
      acp:allow acl:Read, acl:Write ;  
      acp:anyOf ex:matcherA ;
      acp:noneOf ex:matcherB ;
    ] ;
  ] ;
] .

4.4.1. Example Matcher

The following example authorization graph means that Matcher A will be satisfied when either Alice or the owner of the access controlled resource are requesting access.

ex:matcherA
  a acp:Matcher ;
  acp:agent ex:Alice, acp:OwnerAgent .  

The following example authorization graph means that the defined Matcher will be satisfied when matched against a context graph where the client used to access the access controlled resource is client B.

[
  a acp:Matcher ;
  acp:client ex:clientB ;  
] .

The following example authorization graph means that Matcher A will be satisfied when matched against a context graph where the identity provider used to assert the identity of the agent requesting access to the access controlled resource is issuer B.

ex:matcherA
  a acp:Matcher ;
  acp:issuer ex:issuerB .  

The following example authorization graph means that the defined Matcher will be satisfied when matched against a context graph showing that a valid VC of type credential B has been presented by the agent requesting access to the access controlled resource.

[]
  a acp:Matcher ;
  acp:vc ex:credentialB .  

The following example authorization graph means that matcher A will be satisfied only if either Alice or Bob are the agent requesting resource access and their identity was asserted by Identity Provider B.

ex:matcherA
  a acp:Matcher ;
  acp:agent ex:Bob, ex:Alice ;
  acp:issuer ex:IdentityProviderB .  

The following example authorization graph means that the defined matcher will be satisfied only if Alice, whose identity is asserted by Identity Provider B, is the agent requesting resource access and is doing so presenting a VC that is a valid instance of credential A.

[
  a acp:Matcher ;
  acp:agent ex:Alice ;
  acp:issuer ex:IdentityProviderB ;  
  acp:vc ex:credentialA ;
] .

The following example authorization graph means that Policy A denies Read and Write access to all clients but client C and policy B allows read to all clients. If Policy A and B control access to a resource, then anyone using client C will have Read access to that resource.

ex:policyA
  acp:deny acl:Read, acl:Write ;
  acp:anyOf [
    acp:client acp:PublicClient ;  
  ] ,
  acp:noneOf [
    acp:client ex:clientC
  ] .

ex:policyB
  acp:allow acl:Read ;
  acp:anyOf [
    acp:client:PublicClient ;
  ] .

4.5.1. Example Matcher extension

Given the property ex:tag previously defined in the example context extension as a an rdfs:subPropertyOf acp:attribute that describes tags applied to requested resources; the following example context graph would mean that Policy 1 allows Read and is satisfied by instances of resource access initiated over a resource that was tagged ex:FavouriteRecord or ex:Wishlist.

ex:policy1
  acp:allow acl:Read ;
  acp:anyOf [
    ex:tag ex:FavouriteRecord, ex:Wishlist ;  
  ] .

5.1.1. Example Access Grant

The following example access grant graph means that Access Modes acl:Read and acl:Write have been granted to Alice for accessing resource X.

[]
  acp:grant acl:Read, acl:Write ;  
  acp:context [
    acp:agent ex:Alice ;
    acp:target ex:resourceX ;
  ] .

5.2.1. Example Access Mode

The following example access grant graph means that acl:Read and ex:Delete are Access Modes; furthermore, it means that acl:Read and ex:Delete have been granted to Bob over resource X.

[]
  acp:grant acl:Read, ex:Delete ;  
  acp:context [
    acp:target ex:resourceX ;
    acp:agent ex:Bob ;
  ] .

6.1.1. Resolved Access Control pseudocode

function resolveAccessControl(acr, ancestorAcrs, context) {
  const effectivePolicies = gatherEffectivePolicies(acr, ancestorAcrs)
  const allowedAccessModes = grantAccessModes(effectivePolicies, context)
  const grantGraph = {
      context,
      grant: allowedAccessModes
  }

  return grantGraph
}

6.2.1. Effective Policies example

The following example authorization graph means that access to resource X is controlled by both Access Controls B and C, access to resource X is therefore controlled by Policy E and Policy F. The member Access Controls are not taken into account at this level. Member Access Control D will be included in the effective authorization graph of resource X's members' ACRs both as an Access Control and a member Access Control. Therefore, Policy G will be part of the set of effective Policies controlling access to resource X's members and transitively to further members of member resources.

  ex:accessControlResourceA
    acp:resource ex:X ;
    acp:accessControl ex:accessControlB, ex:accessControlC ;  
    acp:memberAccessControl ex:accessControlD .

  ex:accessControlB
    acp:apply ex:PolicyE .

  ex:accessControlC
    acp:apply ex:PolicyF .

  ex:accessControlD
    acp:apply ex:PolicyG .

6.2.2. Effective Policies pseudocode

function gatherEffectivePolicies(acr, ancestorAcrs) {
  const effectivePolicies = new Set

  // Direct access controls of own ACR.
  for (const accessControl of acr.accessControls)
      for (const policy of accessControl.appliedPolicies)
          effectivePolicies.add(policy)

  // Member access controls of ancestor ACRs.
  for (const acr of ancestorAcrs)
      for (const accessControl of acr.memberAccessControls)
          for (const policy of accessControl.appliedPolicies)
              effectivePolicies.add(policy)

  return effectivePolicies
}

6.3.1. Granted Access Modes example

The following example authorization graph means that access to resource X is controlled by Policy B and Policy C. Depending on the satisfaction of Policies B and C, different access modes will be granted.

• If only Policy B is satisfied, then Access Modes acl:Read and acl:Write will be granted.
• If both Policy B and Policy C are satisfied, then only Access Mode acl:Read will be granted.
• If only Policy C is satisfied, then no Access Mode will be granted.

[
  acp:resource ex:X ;
  acp:accessControl [
    acp:apply ex:policyB, ex:policyC ;  
  ]
] .

ex:policyB
  acp:allow acl:Read, acl:Write .

ex:policyC
  acp:deny acl:Write .

6.3.2. Granted Access Modes pseudocode

function grantAccessModes(policies, context) {
  const allowedAccessModes = new Set, deniedAccessModes = new Set

  // Gather allowed and denied access modes from satisfied policies
  for (const policy of policies)
      if (isSatisfiedPolicy(policy, context)) {
          for (const mode of policy.allowedAccessModes)
              allowedAccessModes.add(mode)

          for (const mode of policy.deniedAccessModes)
              deniedAccessModes.add(mode)
      }

  // Deny overrules allow.
  for (const mode of deniedAccessModes)
      allowedAccessModes.delete(mode)

  return allowedAccessModes
}

6.4.1. Satisfied Policy example

The following example authorization graph means that access to resource X is controlled by Policy A. Depending on the satisfaction of Matchers B, C, D, E and F, Policy A will be satisfied or not.

• If either Matcher B or Matcher C are not satisfied, then Policy A will not be satisfied.
• If neither Matcher D nor Matcher E are satisfied, then Policy A will not be satisfied.
• If either Matcher F or Matcher G is satisfied, then Policy A will not be satisfied.
• If both Matcher B and Matcher C are satisfied, and, either Matcher D or Matcher E are satisfied, and, Matcher F and Matcher G are not satisfied, then Policy A will be satisfied.

[
  acp:resource ex:X ;
  acp:accessControl [
    acp:apply ex:policyA ;
  ]
] .

ex:policyA
  acp:allOf ex:matcherB, ex:matcherC ;  
  acp:anyOf ex:matcherD, matcherE ;
  acp:noneOf ex:matcherF, ex:matcherG .

6.4.2. Satisfied Policy pseudocode

function isSatisfiedPolicy(policy, context) {
  // If any 'none of' matcher is satisfied then the policy is not satisfied.
  for (const matcher of policy.noneOfMatchers)
      if (isSatisfiedMatcher(matcher, context))
          return false

  // If any 'all of' matcher is not satisfied then the policy is not satisfied.
  for (const matcher of policy.allOfMatchers)
      if (!isSatisfiedMatcher(matcher, context))
          return false

  // If any 'any of' matcher is satisfied then the policy is satisfied.
  for (const matcher of policy.anyOfMatchers)
      if (isSatisfiedMatcher(matcher, context))
          return true

  // At this point there are
  // - no satisfied 'none of' matchers,
  // - no unsatisfied 'all of' matchers and
  // - no satisfied 'any of' matchers.

  // Hence, the policy is satisfied if it has
  // - an 'all of' condition and
  // - no 'any of' condition.
  return policy.allOfMatchers.size !== 0 && policy.anyOfMatchers === 0
}

6.5.1. Satisfied Matcher example

The following example authorization graph means that access to resource X is controlled by a Policy that will allow read if it is satisfied and be satisfied if either matcher A or matcher B or both are satisfied.

Matcher A will be satisfied if:

• either Alice or Bob are the requesting agent or if the requesting agent is an owner or creator; and,
• client 1 is used by the requesting agent; and,
• issuer 2 is used by the requesting agent to assert their identity.

Matcher B will be satisfied if:

• a valid VC of type "Family Member" is presented.

[
  acp:resource ex:X ;
  acp:accessControl [
    acp:apply [
      acp:allow acl:Read ;
      acp:anyOf ex:matcherA, ex:matcherB ;
    ]
  ]
] .

ex:matcherA
  acp:agent ex:Alice, ex:Bob, acp:CreatorAgent, acp:OwnerAgent ;  
  acp:client ex:client1 ;
  acp:issuer ex:issuer2 .

ex:matcherB
  acp:vc ex:FamilyMember .

6.5.2. Satisfied Matcher pseudocode

function isSatisfiedMatcher(matcher, context) {
  // An empty matcher is never satisfied.
  if (matcher.agents.size === 0 && matcher.clients.size === 0 && matcher.issuers.size === 0 && matcher.vcs.size === 0)
      return false

  // For each attribute, if any values are defined, then at least one of them must match the context.

  if (matcher.agents.size !== 0) {
      let isMatch = false

      for (const agent of matcher.agents)
          if (agentMatches(agent, context)) {
              isMatch = true
              break
          }

      if (!isMatch)
          return false
  }

  if (matcher.clients.size !== 0) {
      let isMatch = false

      for (const client of matcher.clients)
          if (clientMatches(client, context)) {
              isMatch = true
              break
          }

      if (!isMatch)
          return false
  }

  if (matcher.issuers.size !== 0) {
      let isMatch = false

      for (const issuer of matcher.issuers)
          if (issuerMatches(issuer, context)) {
              isMatch = true
              break
          }

      if (!isMatch)
          return false
  }

  if (matcher.vcs.size !== 0) {
      let isMatch = false

      for (const vc of matcher.vcs)
          if (vcMatches(vc, context)) {
              isMatch = true
              break
          }

      if (!isMatch)
          return false
  }

  // At this point, the matcher is satisfied because
  // - there was at least one defined attribute and
  // - at least one value of each defined attribute matched the context.
  return true
}

const publicAgent = "https://www.w3.org/ns/solid/acp#PublicAgent"
const authenticatedAgent = "https://www.w3.org/ns/solid/acp#AuthenticatedAgent"
const creatorAgent = "https://www.w3.org/ns/solid/acp#CreatorAgent"
const ownerAgent = "https://www.w3.org/ns/solid/acp#OwnerAgent"
function agentMatches(agent, context) {
  if (agent === publicAgent)
      return true

  if (agent === authenticatedAgent && context.agent !== null)
      return true

  if (agent === creatorAgent && context.creators.includes(context.agent))
      return true

  if (agent === ownerAgent && context.owners.includes(context.agent))
      return true

  if (agent === context.agent)
      return true
}

const publicClient = "https://www.w3.org/ns/solid/acp#PublicClient"
function clientMatches(client, context) {
  if (client === publicClient)
      return true

  if (client === context.client)
      return true
}

const publicIssuer = "https://www.w3.org/ns/solid/acp#PublicIssuer"
function issuerMatches(issuer, context) {
  if (issuer === publicIssuer)
      return true

  if (issuer === context.issuer)
      return true
}

function vcMatches(vc, context) {
  if (context.vcs.includes(vc))
      return true
}