ood_support 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ab9a0231c41e21de5992f0ae3bcf0be3ed19638
-  data.tar.gz: fce3ab5ef3dc87c42cb8a8af09136aa80705ed7e
+  metadata.gz: 74117abef87ed8fce6977b36e54d99795db90ba2
+  data.tar.gz: f82d7ee819ed4bacece8ea084a3bb472e47105e9
 SHA512:
-  metadata.gz: 0611200202ea6a276b89927499a45c130d54a06d5a6eb865bcf2c413ddefa85458ea3cb887f639e3dea7d8b1a8616d5cdf27dec54b05f8a3a834cf8a86f51878
-  data.tar.gz: 98f312e86afbe33ea1b6d1b5d1e9830feb10a28e149d3cfdbe7692744a7280397b2d2911f55b946daea9cc17a6ebc5ba25cf0e27bf8c0f5843261cdb9d8ef38e
+  metadata.gz: 61abe8f3a20b7d6a9b6c3094d7b3490459dbf6629efd2559c420981ebb7257f7d617399177319fa84801ec48cd13dc44bb336ea1e50e5a35feeac42b43c13cee
+  data.tar.gz: 173d29d517fc5f9da03cefe598e32a195301eb3752d7f982edf74997f0e2cfbc1d0591f4907a0fe7f091bd2e79aadb597f6dbec20ba7ca2eae2c5f1696958644

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## Unreleased
+
+## 0.0.2 (2016-08-26)
+
+Bugfixes:
+
+  - added aliases `User#home` and `User#member_of_group?` for backwards
+    compatibility
+
+## 0.0.1 (2016-07-01)
+
+Initial release!

data/README.md

@@ -156,6 +156,156 @@ OodSupport::Process.groups_changed?
 #=> false
 ```
 
+### ACLs
+
+#### NFSv4 File ACLs
+
+Allows reading and writing of NFSv4 file ACL permissions.
+
+To access a file's ACL:
+
+```ruby
+# Get file ACL
+acl = OodSupport::ACLs::Nfs4ACL.get_facl(path: "/path/to/file")
+
+# Check if user has read access to file
+acl.allow?(principle: OodSupport::User.new("user1"), permission: :r)
+#=> true
+
+# Check if group has write access to file
+# NB: A user of this group may *actually* have access to write to this file
+acl.allow?(principle: OodSupport::Group.new("group1"), permission: :w)
+#=> false
+```
+
+To add an ACL permission to a file:
+
+```ruby
+# Create a new ACL entry
+entry = OodSupport::ACLs::Nfs4Entry.new(type: :A, flags: [], principle: "user2", domain: "osc.edu", permissions: [:r, :w])
+
+# or you can pass it a properly formatted string...
+entry = OodSupport::ACLs::Nfs4Entry.parse("A::user2@osc.edu:rw")
+
+# Add this entry to the file ACLs
+acl = OodSupport::ACLs::Nfs4ACL.add_facl(path: "/path/to/file", entry: entry)
+
+# Check that this added entry changes access
+acl.allow?(principle: OodSupport::User.new("user2"), permission: :r)
+#=> true
+```
+
+To remove an ACL permission from a file:
+
+```ruby
+# Get file ACL
+acl = OodSupport::ACLs::Nfs4ACL.get_facl(path: "/path/to/file")
+
+# Choose the entry we want to remove from the array of entries
+entry = acl.entries.first
+
+# Remove this entry from the file
+new_acl = OodSupport::ACLs::Nfs4ACL.rem_facl(path: "/path/to/file", entry: entry)
+
+# Check that this entry removal changes access
+new_acl.allow?(principle: OodSupport::User.new("user2"), permission: :r)
+#=> false
+```
+
+##### File ACL Methods
+
+List of class methods on the `Nfs4ACL` object used to access/modify a file's
+ACL. For all class methods an `Nfs4ACL` object is created and returned.
+
+```ruby
+# Get the file/directory ACLs for a given path
+Nfs4ACL::get_facl(path: p)
+
+# Add an ACL entry to the given file/directory ACLs
+Nfs4ACL::add_facl(path: p, entry: e)
+
+# Remove an ACL entry from the given file/directory ACLs
+Nfs4ACL::rem_facl(path: p, entry: e)
+
+# Modify in-place an ACL entry from the given file/directory ACLs
+Nfs4ACL::mod_facl(path: p, old_entry: e1, new_entry: e2)
+
+# Set the whole ACL (overwrites original) for a given file/directory
+Nfs4ACL::set_facl(path: p, acl: a)
+```
+
+#### Posix File ACLs
+
+Allows reading and writing of Posix file ACL permissions.
+
+To access a file's ACL:
+
+```ruby
+# Get file ACL
+acl = OodSupport::ACLs::PosixACL.get_facl path: "/path/to/file"
+
+# Check if user has read access to file
+acl.allow?(principle: OodSupport::User.new("user1"), permission: :r)
+#=> true
+
+# Check if group has write access to file
+# NB: A user of this group may *actually* have access to write to this file
+acl.allow?(principle: OodSupport::Group.new("group1"), permission: :w)
+#=> false
+```
+
+To add an ACL permission to a file:
+
+```ruby
+# Create a new ACL entry
+entry = OodSupport::ACLs::PosixEntry.new(flag: :user, principle: "user2", permissions: [:r, :w, :-])
+
+# or you can pass it a properly formatted string...
+entry = OodSupport::ACLs::PosixEntry.parse("user:user2:rw-")
+
+# Add this entry to the file ACLs
+acl = OodSupport::ACLs::PosixACL.add_facl(path: "/path/to/file", entry: entry)
+
+# Check that this added entry changes access
+acl.allow?(principle: OodSupport::User.new("user2"), permission: :r)
+#=> true
+```
+
+To remove an ACL permission from a file:
+
+```ruby
+# Get file ACL
+acl = OodSupport::ACLs::PosixACL.get_facl(path: "/path/to/file")
+
+# Choose the entry we want to remove from the array of entries
+entry = acl.entries.detect {|e| e.user_entry? && e.principle == "user2"}
+
+# Remove this entry from the file
+new_acl = OodSupport::ACLs::PosixACL.rem_facl(path: "/path/to/file", entry: entry)
+
+# Check that this entry removal changes access
+new_acl.allow?(principle: OodSupport::User.new("user2"), permission: :r)
+#=> false
+```
+
+##### File ACL Methods
+
+List of class methods on the `PosixACL` object used to access/modify a file's
+ACL. For all class methods an `PosixACL` object is created and returned.
+
+```ruby
+# Get the file/directory ACLs for a given path
+PosixACL::get_facl(path: p)
+
+# Add an ACL entry to the given file/directory ACLs
+PosixACL::add_facl(path: p, entry: e)
+
+# Remove an ACL entry from the given file/directory ACLs
+PosixACL::rem_facl(path: p, entry: e)
+
+# Clear all extended ACLs for the given file/directory
+PosixACL::clear_facl(path: p)
+```
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/ood_support/fork )

data/lib/ood_support.rb

@@ -1,9 +1,16 @@
 require 'ood_support/version'
+require 'ood_support/errors'
 require 'ood_support/user'
 require 'ood_support/group'
 require 'ood_support/process'
+require 'ood_support/acl'
+require 'ood_support/acl_entry'
 
 # The main namespace for ood_support
 module OodSupport
-  # Your code goes here...
+  # A namespace to hold all subclasses of {ACL} and {ACLEntry}
+  module ACLs
+    require 'ood_support/acls/nfs4'
+    require 'ood_support/acls/posix'
+  end
 end

data/lib/ood_support/acl.rb

@@ -0,0 +1,89 @@
+module OodSupport
+  # A helper object that describes an access control list (ACL) with entries
+  class ACL
+    # The entries of this ACL
+    # @return [Array<ACLEntry>] list of entries
+    attr_reader :entries
+
+    # Whether this ACL defaults to allow, otherwise default deny
+    # @return [Boolean] whether default allow
+    attr_reader :default
+
+    # Generate an ACL by parsing a string along with options
+    # @param acl [#to_s] string describing acl
+    # @param kwargs [Hash] extra arguments defining acl
+    # @return [ACL] acl generated by string and options
+    def self.parse(acl, **kwargs)
+      entries = []
+      acl.to_s.strip.split(/\n|,/).grep(/^[^#]/).each do |entry|
+        entries << entry_class.parse(entry)
+      end
+      new(entries: entries, **kwargs)
+    end
+
+    # @param entries [#to_s] list of entries
+    # @param default [Boolean] default allow, otherwise deny
+    def initialize(entries:, default: false)
+      @entries = entries
+      @default = default
+    end
+
+    # Check if queried principle has access to resource
+    # @param principle [String] principle to check against
+    # @return [Boolean] does principle have access?
+    def allow?(principle:)
+      # Check in array order
+      ordered_check(principle: principle)
+    end
+
+    # Convert object to string
+    # @return [String] the string describing this object
+    def to_s
+      entries.join("\n")
+    end
+
+    # Convert object to hash
+    # @return [Hash] the hash describing this object
+    def to_h
+      { entries: entries, default: default }
+    end
+
+    # The comparison operator
+    # @param other [#to_h] entry to compare against
+    # @return [Boolean] how acls compare
+    def ==(other)
+      to_h == other.to_h
+    end
+
+    # Checks whether two ACL objects are completely identical to each other
+    # @param other [ACL] entry to compare against
+    # @return [Boolean] whether same objects
+    def eql?(other)
+      self.class == other.class && self == other
+    end
+
+    # Generates a hash value for this object
+    # @return [Fixnum] hash value of object
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+      # Class used to generate an entry
+      def self.entry_class
+        ACLEntry
+      end
+
+      # Check each entry in order from array
+      def ordered_check(**kwargs)
+        entries.each do |entry|
+          if entry.match(**kwargs)
+            # Check if its an allow or deny acl entry (may not be both)
+            return true  if entry.is_allow?
+            return false if entry.is_deny?
+          end
+        end
+        return default # default allow or default deny
+      end
+  end
+end

data/lib/ood_support/acl_entry.rb

@@ -0,0 +1,76 @@
+module OodSupport
+  # A helper object that defines a generic ACL entry
+  class ACLEntry
+    include Comparable
+
+    # The principle of this entry
+    # @return [String] principle of entry
+    attr_reader :principle
+
+    # Generate an entry by parsing a string
+    # @param entry [#to_s] string describing entry
+    # @param kwargs [Hash] extra arguments
+    # @raise [InvalidACLEntry] unable to parse entry string
+    # @return [ACLEntry] entry generated by string
+    def self.parse(entry, **kwargs)
+      new(parse_entry(entry).merge(kwargs))
+    end
+
+    # @param principle [#to_s] principle for this ACL entry
+    def initialize(principle:)
+      @principle = principle.to_s
+    end
+
+    # Is this an "allow" ACL entry
+    # @return [Boolean] is this an allow entry
+    def is_allow?
+      true
+    end
+
+    # Is this a "deny" ACL entry
+    # @return [Boolean] is this a deny entry
+    def is_deny?
+      !is_allow?
+    end
+
+    # Do the requested args match this ACL entry?
+    # @params principle [String] requested principle
+    # @return [Boolean] does this match this entry
+    def match(principle:)
+      self.principle == principle
+    end
+
+    # Convert object to string
+    # @return [String] the string describing this object
+    def to_s
+      principle
+    end
+
+    # The comparison operator
+    # @param other [#to_s] entry to compare against
+    # @return [Boolean] how entries compare
+    def <=>(other)
+      to_s <=> other
+    end
+
+    # Checks whether two ACLEntry objects are completely identical to each
+    # other
+    # @param other [ACLEntry] entry to compare against
+    # @return [Boolean] whether same objects
+    def eql?(other)
+      self.class == other.class && self == other
+    end
+
+    # Generates a hash value for this object
+    # @return [Fixnum] hash value of object
+    def hash
+      [self.class, to_s].hash
+    end
+
+    private
+      # Parse an entry string into input parameters
+      def self.parse_entry(entry)
+       { principle: entry.to_s.strip }
+      end
+  end
+end

data/lib/ood_support/acls/nfs4.rb

@@ -0,0 +1,262 @@
+require 'open3'
+
+module OodSupport
+  module ACLs
+    # Object describing an NFSv4 ACL
+    class Nfs4ACL < ACL
+      # The binary used to get the file ACLs
+      GET_FACL_BIN = 'nfs4_getfacl'
+
+      # The binary used to set the file ACLs
+      SET_FACL_BIN = 'nfs4_setfacl'
+
+      # Name of owner for this ACL
+      # @return [String] owner name
+      attr_reader :owner
+
+      # Name of owning group for this ACL
+      # @return [String] group name
+      attr_reader :group
+
+      # Get ACL from file path
+      # @param path [String] path to file or directory
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [Nfs4ACL] acl generated from path
+      def self.get_facl(path:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        stat = path.stat
+        acl, err, s = Open3.capture3(GET_FACL_BIN, path.to_s)
+        raise BadExitCode, err unless s.success?
+        parse(acl, owner: User.new(stat.uid), group: Group.new(stat.gid))
+      end
+
+      # Add ACL to file path
+      # @param path [String] path to file or directory
+      # @param entry [Nfs4Entry] entry to add to file
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [Nfs4ACL] new acl of path
+      def self.add_facl(path:, entry:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-a', entry.to_s, path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Remove ACL from file path
+      # @param path [String] path to file or directory
+      # @param entry [Nfs4Entry] entry to remove from file
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [Nfs4ACL] new acl of path
+      def self.rem_facl(path:, entry:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-x', entry.to_s, path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Modify in-place an entry for file path
+      # @param path [String] path to file or directory
+      # @param old_entry [Nfs4Entry] old entry to modify in-place in file
+      # @param new_entry [Nfs4Entry] new entry to be replaced with
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [Nfs4ACL] new acl of path
+      def self.mod_facl(path:, old_entry:, new_entry:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-m', old_entry.to_s, new_entry.to_s, path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Set ACL (overwrites original) for file path
+      # @param path [String] path to file or directory
+      # @param acl [Nfs4ACL] ACL to overwrite original with
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [Nfs4ACL] new acl of path
+      def self.set_facl(path:, acl:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-s', acl.to_s, path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # @param owner [#to_s] name of owner
+      # @param group [#to_s] name of group
+      # @see ACL#initialize
+      def initialize(owner:, group:, **kwargs)
+        super(kwargs.merge(default: false))
+        @owner = owner.to_s
+        @group = group.to_s
+      end
+
+      # Check if queried principle has access to resource
+      # @param principle [User, Group] principle to check against
+      # @param permission [Symbol] permission to check against
+      # @return [Boolean] does principle have access?
+      def allow?(principle:, permission:)
+        # Check in array order
+        ordered_check(principle: principle, permission: permission, owner: owner, group: group)
+      end
+
+      # Convert object to hash
+      # @return [Hash] the hash describing this object
+      def to_h
+        super.merge owner: owner, group: group
+      end
+
+      private
+        # Use Nfs4Entry for entry objects
+        def self.entry_class
+          Nfs4Entry
+        end
+    end
+
+    # Object describing single NFSv4 ACL entry
+    class Nfs4Entry < ACLEntry
+      # Valid types for an ACL entry
+      VALID_TYPE = %i[ A U D L ]
+
+      # Valid flags for an ACL entry
+      VALID_FLAG = %i[ f d p i S F g ]
+
+      # Valid permissions for an ACL entry
+      VALID_PERMISSION = %i[ r w a x d D t T n N c C o y ]
+
+      # Regular expression used when parsing ACL entry string
+      REGEX_PATTERN = %r[^(?<type>[#{VALID_TYPE.join}]):(?<flags>[#{VALID_FLAG.join}]*):(?<principle>\w+)@(?<domain>[\w\.\-]*):(?<permissions>[#{VALID_PERMISSION.join}]+)$]
+
+      # Type of ACL entry
+      # @return [Symbol] type of acl entry
+      attr_reader :type
+
+      # Flags set on ACL entry
+      # @return [Array<Symbol>] flags on acl entry
+      attr_reader :flags
+
+      # Domain of ACL entry
+      # @return [String] domain of acl entry
+      attr_reader :domain
+
+      # Permissions of ACL entry
+      # @return [Array<Symbol>] permissions of acl entry
+      attr_reader :permissions
+
+      # @param type [#to_sym] type of acl entry
+      # @param flags [Array<#to_sym>] list of flags for entry
+      # @param domain [#to_s] domain of principle
+      # @param permissions [Array<#to_sym>] list of permissions for entry
+      # @see ACLEntry#initialize
+      def initialize(type:, flags:, domain:, permissions:, **kwargs)
+        @type = type.to_sym
+        @flags = flags.map(&:to_sym)
+        @domain = domain.to_s
+        @permissions = permissions.map(&:to_sym)
+        super(kwargs)
+      end
+
+      # Is this an "allow" ACL entry
+      # @return [Boolean] is this an allow entry
+      def is_allow?
+        type == :A
+      end
+
+      # Is this a "deny" ACL entry
+      # @return [Boolean] is this a deny entry
+      def is_deny?
+        type == :D
+      end
+
+      # Do the requested args match this ACL entry?
+      # @param principle [User, Group, #to_s] requested principle
+      # @param permission [#to_sym] requested permission
+      # @param owner [String] owner of corresponding ACL
+      # @param group [String] owning group of corresponding ACL
+      # @raise [ArgumentError] principle isn't {User} or {Group} object
+      # @return [Boolean] does this match this entry
+      def match(principle:, permission:, owner:, group:)
+        principle = User.new(principle) if (!principle.is_a?(User) && !principle.is_a?(Group))
+        return false unless has_permission?(permission: permission)
+        # Ignore domain, I don't want or care to check for domain matches
+        p = self.principle
+        p = owner if user_owner_entry?
+        p = group if group_owner_entry?
+        if (principle.is_a?(User) && group_entry?)
+          principle.groups.include?(p)
+        elsif (principle.is_a?(User) && user_entry?) || (principle.is_a?(Group) && group_entry?)
+          principle == p
+        elsif other_entry?
+          true
+        else
+          false
+        end
+      end
+
+      # Is this a user-specific ACL entry
+      # @return [Boolean] is this a user entry
+      def user_entry?
+        !group_entry? && !other_entry?
+      end
+
+      # Is this a group-specific ACL entry
+      # @return [Boolean] is this a group entry
+      def group_entry?
+        flags.include? :g
+      end
+
+      # Is this an other-specific ACL entry
+      # @return [Boolean] is this an other entry
+      def other_entry?
+        principle == "EVERYONE"
+      end
+
+      # Is this the owner ACL entry
+      # @return [Boolean] is this the owner entry
+      def user_owner_entry?
+        user_entry? && principle == "OWNER"
+      end
+
+      # Is this the owning group ACL entry
+      # @return [Boolean] is this the owning group entry
+      def group_owner_entry?
+        group_entry? && principle == "GROUP"
+      end
+
+      # Does this entry have the requested permission
+      # @param permission [#to_sym] the requested permission
+      # @return [Boolean] found this permission
+      def has_permission?(permission:)
+        permissions.include? permission.to_sym
+      end
+
+      # Convert object to string
+      # @return [String] the string describing this object
+      def to_s
+        "#{type}:#{flags.join}:#{principle}@#{domain}:#{permissions.join}"
+      end
+
+      private
+        # Parse an entry string into input parameters
+        def self.parse_entry(entry)
+          e = REGEX_PATTERN.match(entry.to_s.strip) do |m|
+            {
+              type:        m[:type],
+              flags:       m[:flags].chars,
+              principle:   m[:principle],
+              domain:      m[:domain],
+              permissions: m[:permissions].chars
+            }
+          end
+          e ? e : raise(InvalidACLEntry, "invalid entry: #{entry}")
+        end
+    end
+  end
+end

data/lib/ood_support/acls/posix.rb

@@ -0,0 +1,274 @@
+require 'open3'
+
+module OodSupport
+  module ACLs
+    # Object describing a Posix ACL
+    class PosixACL < ACL
+      # The binary used to get the file ACLs
+      GET_FACL_BIN = 'getfacl'
+
+      # The binary used to set the file ACLs
+      SET_FACL_BIN = 'setfacl'
+
+      # Name of owner for this ACL
+      # @return [String] owner name
+      attr_reader :owner
+
+      # Name of owning group for this ACL
+      # @return [String] group name
+      attr_reader :group
+
+      # Mask set for this ACL
+      # @return [Array<Symbol>] mask for this acl
+      attr_reader :mask
+
+      # Get ACL from file path
+      # @param path [String] path to file or directory
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [PosixACL] acl generated from path
+      def self.get_facl(path:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        stat = path.stat
+        acl, err, s = Open3.capture3(GET_FACL_BIN, path.to_s)
+        raise BadExitCode, err unless s.success?
+        parse(acl, owner: User.new(stat.uid), group: Group.new(stat.gid))
+      end
+
+      # Add ACL to file path
+      # @param path [String] path to file or directory
+      # @param entry [PosixEntry] entry to add to file
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [PosixACL] new acl of path
+      def self.add_facl(path:, entry:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-m', entry.to_s, path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Remove ACL from file path
+      # @param path [String] path to file or directory
+      # @param entry [PosixEntry] entry to remove from file
+      # @raise [InvalidPath] file path doesn't exist
+      # @raise [BadExitCode] the command line called exited with non-zero status
+      # @return [PosixACL] new acl of path
+      def self.rem_facl(path:, entry:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-x', entry.to_s(w_perms: false), path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Clear all extended ACLs from file path
+      # @param path [String] path to file or directory
+      # @return [PosixACL] new acl of path
+      def self.clear_facl(path:)
+        path = Pathname.new path
+        raise InvalidPath, "invalid path: #{path}" unless path.exist?
+        _, err, s = Open3.capture3(SET_FACL_BIN, '-b', path.to_s)
+        raise BadExitCode, err unless s.success?
+        get_facl(path: path)
+      end
+
+      # Generate an ACL by parsing a string along with options
+      # @param acl [#to_s] string describing acl
+      # @param kwargs [Hash] extra arguments defining acl
+      # @return [PosixACL] acl generated by string and options
+      def self.parse(acl, **kwargs)
+        entries = []
+        acl.to_s.strip.split(/\n|,/).grep(/^[^#]/).each do |entry|
+          entries << entry_class.parse(entry)
+        end
+        mask = entries.detect {|e| e.flag == :mask}
+        new(entries: entries - [mask], mask: mask, **kwargs)
+      end
+
+      # @param owner [#to_s] name of owner
+      # @param group [#to_s] name of group
+      # @param mask [PosixACL] mask permissions
+      # @see ACL#initialize
+      def initialize(owner:, group:, mask:, **kwargs)
+        super(kwargs.merge(default: false))
+        @owner = owner.to_s
+        @group = group.to_s
+        @mask = mask
+      end
+
+      # Check if queried principle has access to resource
+      # @param principle [User, Group] principle to check against
+      # @param permission [Symbol] permission to check against
+      # @return [Boolean] does principle have access?
+      def allow?(principle:, permission:)
+        # First check owner entry then check rest of user entries (order
+        # matters). If match, then this entry determines access.
+        entries.select(&:user_entry?).sort_by {|e| e.user_owner_entry? ? 0 : 1}.each do |entry|
+          return entry.has_permission?(permission: permission, mask: mask) if entry.match(principle: principle, owner: owner, group: group)
+        end
+
+        # Then check groups (order independent). Entry only determines access
+        # if it contains requested permission.
+        groups = entries.select {|e| e.group_entry? && e.match(principle: principle, owner: owner, group: group)}.map do |entry|
+          entry.has_permission?(permission: permission, mask: mask)
+        end
+
+        unless groups.empty?
+          # Found matching groups so check if any give access
+          groups.any?
+        else
+          # Failed to find any matching groups so check "other" entry
+          entries.detect(&:other_entry?).has_permission?(permission: permission, mask: mask)
+        end
+      end
+
+      # Convert object to string
+      # @return [String] the string describing the object
+      def to_s
+        (entries + [mask]).join(",")
+      end
+
+      # Convert object to hash
+      # @return [Hash] the hash describing this object
+      def to_h
+        super.merge owner: owner, group: group, mask: mask
+      end
+
+      private
+        # Use PosixEntry for entry objects
+        def self.entry_class
+          PosixEntry
+        end
+    end
+
+    # Object describing single Posix ACL entry
+    class PosixEntry < ACLEntry
+      # Valid flags for an ACL entry
+      VALID_FLAG = %i[ user group mask other ]
+
+      # Valid permissions for an ACL entry
+      VALID_PERMISSION = %i[ r w x ]
+
+      # Regular expression used when parsing ACL entry string
+      REGEX_PATTERN = %r[^(?<default>default:)?(?<flag>#{VALID_FLAG.join('|')}):(?<principle>\w*):(?<permissions>[#{VALID_PERMISSION.join}\-]{3})]
+
+      # Is this a default ACL entry
+      # @return [Boolean] whether default acl entry
+      attr_reader :default
+
+      # Flag set on ACL entry
+      # @return [Symbol] flag on acl entry
+      attr_reader :flag
+
+      # Permissions of ACL entry
+      # @return [Array<Symbol>] permissions of acl entry
+      attr_reader :permissions
+
+      # @param default [Boolean] whether default acl entry
+      # @param flag [#to_sym] flag for entry
+      # @param permissions [Array<#to_sym>] list of permissions for entry
+      # @see ACLEntry#initialize
+      def initialize(default: false, flag:, permissions:, **kwargs)
+        @default = default
+        @flag = flag.to_sym
+        @permissions = permissions.map(&:to_sym)
+        super(kwargs)
+      end
+
+      # Do the requested args match this ACL entry?
+      # @param principle [User, Group, #to_s] requested principle
+      # @param owner [String] owner of corresponding ACL
+      # @param group [String] owning group of corresponding ACL
+      # @raise [ArgumentError] principle isn't {User} or {Group} object
+      # @return [Boolean] does this match this entry
+      def match(principle:, owner:, group:)
+        principle = User.new(principle) if (!principle.is_a?(User) && !principle.is_a?(Group))
+        return false if default_entry?
+        p = self.principle
+        p = owner if user_owner_entry?
+        p = group if group_owner_entry?
+        if (principle.is_a?(User) && group_entry?)
+          principle.groups.include?(p)
+        elsif (principle.is_a?(User) && user_entry?) || (principle.is_a?(Group) && group_entry?)
+          principle == p
+        elsif other_entry?
+          true
+        else
+          false
+        end
+      end
+
+      # Is this a default ACL entry
+      # @return [Boolean] is this a default entry
+      def default_entry?
+        default
+      end
+
+      # Is this a user-specific ACL entry
+      # @return [Boolean] is this a user entry
+      def user_entry?
+        !default_entry? && flag == :user
+      end
+
+      # Is this a group-specific ACL entry
+      # @return [Boolean] is this a group entry
+      def group_entry?
+        !default_entry? && flag == :group
+      end
+
+      # Is this an other-specific ACL entry
+      # @return [Boolean] is this an other entry
+      def other_entry?
+        !default_entry? && flag == :other
+      end
+
+      # Is this the owner ACL entry
+      # @return [Boolean] is this the owner entry
+      def user_owner_entry?
+        user_entry? && principle.empty?
+      end
+
+      # Is this the owning group ACL entry
+      # @return [Boolean] is this the owning group entry
+      def group_owner_entry?
+        group_entry? && principle.empty?
+      end
+
+      # Does this entry have the requested permission
+      # @param permission [#to_sym] the requested permission
+      # @param mask [PosixEntry] the permissions of the mask entry
+      # @return [Boolean] found this permission
+      def has_permission?(permission:, mask:)
+        if user_owner_entry? || other_entry?
+          permissions.include? permission.to_sym
+        else
+          (mask ? permissions & mask.permissions : permissions).include? permission.to_sym
+        end
+      end
+
+      # Convert object to string
+      # @param w_perms [Boolean] whether display permissions
+      # @return [String] the string describing this object
+      def to_s(w_perms: true)
+        %[#{"default:" if default_entry?}#{flag}:#{principle}#{":#{permissions.join}" if w_perms}]
+      end
+
+      private
+        # Parse an entry string into input parameters
+        def self.parse_entry(entry)
+          e = REGEX_PATTERN.match(entry.to_s.strip) do |m|
+            {
+              default:     m[:default] ? true : false,
+              flag:        m[:flag],
+              principle:   m[:principle],
+              permissions: m[:permissions].chars
+            }
+          end
+          e ? e : raise(InvalidACLEntry, "invalid entry: #{entry}")
+        end
+    end
+  end
+end

data/lib/ood_support/errors.rb

@@ -0,0 +1,16 @@
+module OodSupport
+  # The root exception class that all OodSupport-specific exceptions inherit
+  # from
+  class Error < StandardError; end
+
+  # An exception raised when attempting to access a path that doesn't exist on
+  # local file system
+  class InvalidPath < Error; end
+
+  # An exception raised when attempting to run a command that exits with an
+  # exit code other than 0
+  class BadExitCode < Error; end
+
+  # An exception raised when attempting to parse an ACL entry from a string
+  class InvalidACLEntry < Error; end
+end

data/lib/ood_support/group.rb

@@ -25,7 +25,7 @@ module OodSupport
     end
 
     # The comparison operator for sorting values
-    # @param other [Group] group to compare against
+    # @param other [#to_s] group to compare against
     # @return [Fixnum] how groups compare
     def <=>(other)
       name <=> other
@@ -36,13 +36,13 @@ module OodSupport
     # @param other [Group] group to compare against
     # @return [Boolean] whether same objects
     def eql?(other)
-      other.is_a?(Group) && id == other.id
+      self.class == other.class && self == other
     end
 
     # Generates a hash value for this object
     # @return [Fixnum] hash value of object
     def hash
-      id.hash
+      [self.class, name].hash
     end
 
     # Convert object to string using group name as string value

data/lib/ood_support/user.rb

@@ -28,6 +28,8 @@ module OodSupport
 
     alias_method :id, :uid
 
+    alias_method :home, :dir
+
     # @param user [Fixnum, #to_s] user id or name
     def initialize(user = Process.user)
       @passwd = user.is_a?(Fixnum) ? Etc.getpwuid(user) : Etc.getpwnam(user.to_s)
@@ -40,6 +42,8 @@ module OodSupport
       groups.include? Group.new(group)
     end
 
+    alias_method :member_of_group?, :in_group?
+
     # Provide primary group of user
     # @return [Group] primary group of user
     def group
@@ -53,7 +57,7 @@ module OodSupport
     end
 
     # The comparison operator for sorting values
-    # @param other [User] user to compare against
+    # @param other [#to_s] user to compare against
     # @return [Fixnum] how users compare
     def <=>(other)
       name <=> other
@@ -64,13 +68,13 @@ module OodSupport
     # @param other [User] user to compare against
     # @return [Boolean] whether same objects
     def eql?(other)
-      other.is_a?(User) && id == other.id
+      self.class == other.class && self == other
     end
 
     # Generates a hash value for this object
     # @return [Fixnum] hash value of object
     def hash
-      id.hash
+      [self.class, name].hash
     end
 
     # Convert object to string using user name as string value

data/lib/ood_support/version.rb

@@ -1,4 +1,4 @@
 module OodSupport
   # The current version of {OodSupport}
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ood_support
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jeremy Nicklas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-01 00:00:00.000000000 Z
+date: 2016-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -47,11 +47,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/ood_support.rb
+- lib/ood_support/acl.rb
+- lib/ood_support/acl_entry.rb
+- lib/ood_support/acls/nfs4.rb
+- lib/ood_support/acls/posix.rb
+- lib/ood_support/errors.rb
 - lib/ood_support/group.rb
 - lib/ood_support/process.rb
 - lib/ood_support/user.rb