Merge branch 'feature-username-selector'

languitar · languitar · commit 2cc348bc6430 · 2018-11-10T12:11:15.000+01:00
More flexible selection strategies for usernames (and passwords internally). fixes #8 and fixes #9
diff --git a/README.md b/README.md
@@ -4,13 +4,13 @@
 
 [![Debian CI](https://badges.debian.net/badges/debian/testing/pass-git-helper/version.svg)](https://buildd.debian.org/pass-git-helper) [![AUR](https://img.shields.io/aur/version/pass-git-helper.svg)](https://aur.archlinux.org/packages/pass-git-helper/)
 
-A [git] credential helper implementation that allows to use [pass] as the credential backend for your git repositories.
+A [git] credential helper implementation that allows using [pass] as the credential backend for your git repositories.
 This is achieved by explicitly defining mappings between hosts and entries in the password store.
 
 ## Preconditions
 
 GPG must be configured to use a graphical pinentry dialog.
-The shell cannot be used due to the interaction required by [git]
+The shell cannot be used due to the interaction required by [git].
 
 ## Installation
 
@@ -31,7 +31,7 @@ Ensure that `~/.local/bin` is in your `PATH` for the single-user installation.
 Create the file `~/.config/pass-git-helper/git-pass-mapping.ini`.
 This file uses ini syntax to specify the mapping of hosts to entries in the passwordstore database.
 Section headers define patterns which are matched against the host part of a URL with a git repository.
-Matching supports wildcards (using the python [fnmatch module](https://docs.python.org/3.4/library/fnmatch.html)).
+Matching supports wildcards (using the python [fnmatch module](https://docs.python.org/3.7/library/fnmatch.html)).
 Each section needs to contain a `target` entry pointing to the entry in the password store with the password (and optionally username) to use.
 
 Example:
@@ -81,25 +81,71 @@ target=git-logins/${host}
 ```
 The above configuration directive will lead to any host that did not match any previous section in the ini file to being looked up under the `git-logins` directory in your passwordstore.
 
-## Passwordstore Layout
+### DEFAULT section
+
+Defaults suitable for all entries of the mapping file can be specified in a special section of the configuration file named `[DEFAULT]`.
+Everything configure in this section will automatically be available for all further entries in the file, but can be overriden there, too.
+
+## Passwordstore Layout and Data Extraction
+
+### Password
 
 As usual with [pass], this helper assumes that the password is contained in the first line of the passwordstore entry.
-Additionally, if a second line is present, this line is interpreted as the username and also returned back to the git process invoking this helper.
-In case you use markers at the start of lines to identify what is contained in this line, e.g. like `Username: fooo`, the options `skip_username` and `skip_password` can be defined in each mapping to skip the given amount of characters from the beginning of the respective line.
-Additionally, global defaults can be configured via the `DEFAULT` section:
+Though uncommon, it is possible to strip a prefix from the data of the first line (such as `password:` by specifying an amount of characters to leave out in the `skip_password` field for an entry or also in the `[DEFAULT]` section to apply for all entries:
+
 ```ini
 [DEFAULT]
-# this is actually the default
-skip_password=0
-# Lenght of "Username: "
-skip_username=10
+# length of "password: "
+skip_password=10
 
 [somedomain]
-target=special/somedomain
-# somehow this entry does not have a prefix for the username
-skip_username=0
+# for some reasons, this entry doesn't have a password prefix
+skip_password=0
+target=special/noprefix
 ```
 
+### Username
+
+`pass-git-helper` can also provide the username necessary for authenticating at a server.
+In contrast to the password, no clear convention exists how username information is stored in password entries.
+Therefore, multiple strategies to extract the username are implemented and can be selected globally for the whole passwordstore in the `[DEFAULT]` section, or individually for certain entries using the `username_extractor` key:
+
+```ini
+[DEFAULT]
+username_extractor=regex_search
+regex_username=^user: (.*)$
+
+[differingdomain.com]
+# use a fixed line here instead of a regex search
+username_extractor=specific_line
+line_username=1
+```
+
+The following strategies can be configured:
+
+#### Strategy "specific_line" (default)
+
+Extracts the data from a line indexed by its line number.
+Optionally a fixed-length prefix can be stripped before returning the line contents.
+
+Configuration:
+* `line_username`: Line number containing the username, **0-based**. Default: 1 (second line)
+* `skip_username`: Number of characters to skip at the beginning of the line, for instance to skip a `user: ` prefix. Similar to `skip_password`. Default: 0.
+
+#### Strategy "regex_search"
+
+Searches for the first line that matches a provided regular expressions and returns the contents of that line that are captured in a regular expression capture group.
+
+Configuration:
+* `regex_username`: The regular expression to apply. Has to contain a single capture group for indicating the data to extract. Default: `^username: +(.*)$`.
+
+#### Strategy "entry_name"
+
+Returns the last path fragment of the passwordstore entry as the username.
+For instance, if a regular [pass] call would be `pass show dev/github.com/languitar`, the returned username would be `languitar`.
+
+No configuration options.
+
 ## Command Line Options
 
 `-l` can be given as an option to the script to produce logging output on stderr.
diff --git a/passgithelper.py b/passgithelper.py
@@ -7,15 +7,17 @@
 """
 
 
+import abc
 import argparse
 import configparser
 import fnmatch
 import logging
 import os
 import os.path
+import re
 import subprocess
 import sys
-from typing import Dict, Optional, Sequence
+from typing import Dict, Optional, Sequence, Text
 
 import xdg.BaseDirectory
 
@@ -125,6 +127,200 @@ def parse_request() -> Dict[str, str]:
     return request
 
 
+class DataExtractor(abc.ABC):
+    """Interface for classes that extract values from pass entries."""
+
+    def __init__(self, option_suffix: Text = ''):
+        """
+        Create a new instance.
+
+        Args:
+            option_suffix:
+                Suffix to put behind names of configuration keys for this
+                instance. Subclasses must use this for their own options.
+        """
+        self._option_suffix = option_suffix
+
+    @abc.abstractmethod
+    def configure(self, config: configparser.SectionProxy):
+        """
+        Configure the extractor from the mapping section.
+
+        Args:
+            config:
+                configuration section for the entry
+        """
+        pass
+
+    @abc.abstractmethod
+    def get_value(self,
+                  entry_name: Text,
+                  entry_lines: Sequence[Text]) -> Optional[Text]:
+        """
+        Return the extracted value.
+
+        Args:
+            entry_name:
+                Name of the pass entry the value shall be extracted from
+            entry_lines:
+                The entry contents as a sequence of text lines
+
+        Returns:
+            The extracted value or ``None`` if nothing applicable can be found
+            in the entry.
+        """
+        pass
+
+
+class SkippingDataExtractor(DataExtractor):
+    """
+    Extracts data from a pass entry and optionally strips a prefix.
+
+    The prefix is a fixed amount of characters.
+    """
+
+    def __init__(self, prefix_length: int, option_suffix: Text = '') -> None:
+        """
+        Create a new instance.
+
+        Args:
+            prefix_length:
+                Amount of characters to skip at the beginning of the entry
+        """
+        super().__init__(option_suffix)
+        self._prefix_length = prefix_length
+
+    @abc.abstractmethod
+    def configure(self, config):
+        """Configure the amount of characters to skip."""
+        self._prefix_length = config.getint(
+            'skip{suffix}'.format(suffix=self._option_suffix),
+            fallback=self._prefix_length)
+
+    @abc.abstractmethod
+    def _get_raw(self,
+                 entry_name: Text,
+                 entry_lines: Sequence[Text]) -> Optional[Text]:
+        pass
+
+    def get_value(self,
+                  entry_name: Text,
+                  entry_lines: Sequence[Text]) -> Optional[Text]:
+        """See base class method."""
+        raw_value = self._get_raw(entry_name, entry_lines)
+        if raw_value is not None:
+            return raw_value[self._prefix_length:]
+        else:
+            return None
+
+
+class SpecificLineExtractor(SkippingDataExtractor):
+    """Extracts a specific line number from an entry."""
+
+    def __init__(self,
+                 line: int, prefix_length: int,
+                 option_suffix: Text = '') -> None:
+        """
+        Create a new instance.
+
+        Args:
+            line:
+                the line to extract, counting from zero
+            prefix_length:
+                Amount of characters to skip at the beginning of the line
+            option_suffix:
+                Suffix for each configuration option
+        """
+        super().__init__(prefix_length, option_suffix)
+        self._line = line
+
+    def configure(self, config):
+        """See base class method."""
+        super().configure(config)
+        self._line = config.getint(
+            'line{suffix}'.format(suffix=self._option_suffix),
+            fallback=self._line)
+
+    def _get_raw(self,
+                 entry_name: Text,
+                 entry_lines: Sequence[Text]) -> Optional[Text]:
+        if len(entry_lines) > self._line:
+            return entry_lines[self._line]
+        else:
+            return None
+
+
+class RegexSearchExtractor(DataExtractor):
+    """Extracts data using a regular expression with capture group."""
+
+    def __init__(self, regex: str, option_suffix: str):
+        """
+        Create a new instance.
+
+        Args:
+            regex:
+                The regular expression describing the entry line to match. The
+                first matching line is selected. The expression must contain a
+                single capture group that contains the data to return.
+            option_suffix:
+                Suffix for each configuration option
+        """
+        super().__init__(option_suffix)
+        self._regex = self._build_matcher(regex)
+
+    def _build_matcher(self, regex):
+        matcher = re.compile(regex)
+        if matcher.groups != 1:
+            raise ValueError('Provided regex "{regex}" must contain a single '
+                             'capture group for the value to return.'.format(
+                                 regex=regex))
+        return matcher
+
+    def configure(self, config):
+        """See base class method."""
+        super().configure(config)
+
+        self._regex = self._build_matcher(config.get(
+            'regex{suffix}'.format(suffix=self._option_suffix),
+            fallback=self._regex.pattern))
+
+    def get_value(self,
+                  entry_name: Text,
+                  entry_lines: Sequence[Text]) -> Optional[Text]:
+        """See base class method."""
+        # Search through all lines and return the first matching one
+        for line in entry_lines:
+            match = self._regex.match(line)
+            if match:
+                return match.group(1)
+        # nothing matched
+        return None
+
+
+class EntryNameExtractor(DataExtractor):
+    """Return the last path fragment of the pass entry as the desired value."""
+
+    def configure(self, config):
+        """Configure nothing."""
+        pass
+
+    def get_value(self,
+                  entry_name: Text,
+                  entry_lines: Sequence[Text]) -> Optional[Text]:
+        """See base class method."""
+        return os.path.split(entry_name)[1]
+
+
+_line_extractor_name = 'specific_line'
+_username_extractors = {
+    _line_extractor_name: SpecificLineExtractor(
+        1, 0, option_suffix='_username'),
+    'regex_search': RegexSearchExtractor(r'^username: +(.*)$',
+                                         option_suffix='_username'),
+    'entry_name': EntryNameExtractor(option_suffix='_username'),
+}
+
+
 def get_password(request, mapping) -> None:
     """
     Resolve the given credential request in the provided mapping definition.
@@ -147,8 +343,8 @@ def get_password(request, mapping) -> None:
     if 'path' in request:
         host = '/'.join([host, request['path']])
 
-    def decode_skip(line, skip):
-        return line.decode('utf-8')[skip:]
+    def skip(line, skip):
+        return line[skip:]
 
     LOGGER.debug('Iterating mapping to match against host "%s"', host)
     for section in mapping.sections():
@@ -158,19 +354,29 @@ def decode_skip(line, skip):
             # TODO handle exceptions
             pass_target = mapping.get(section, 'target').replace(
                 "${host}", request['host'])
-            skip_password_chars = mapping.getint(
-                section, 'skip_password', fallback=0)
-            skip_username_chars = mapping.getint(
-                section, 'skip_username', fallback=0)
+
+            password_extractor = SpecificLineExtractor(
+                0, 0, option_suffix='_password')
+            password_extractor.configure(mapping[section])
+            # username_extractor = SpecificLineExtractor(
+            #     1, 0, option_suffix='_username')
+            username_extractor = _username_extractors[mapping[section].get(
+                'username_extractor', fallback=_line_extractor_name)]
+            username_extractor.configure(mapping[section])
+
             LOGGER.debug('Requesting entry "%s" from pass', pass_target)
-            output = subprocess.check_output(['pass', 'show', pass_target])
+            output = subprocess.check_output(
+                ['pass', 'show', pass_target]).decode('utf-8')
             lines = output.splitlines()
-            if len(lines) >= 1:
-                print('password={}'.format(  # noqa: P101
-                    decode_skip(lines[0], skip_password_chars)))
-            if 'username' not in request and len(lines) >= 2:
-                print('username={}'.format(  # noqa: P101
-                    decode_skip(lines[1], skip_username_chars)))
+
+            password = password_extractor.get_value(pass_target, lines)
+            username = username_extractor.get_value(pass_target, lines)
+            if password:
+                print('password={password}'.format(  # noqa: T001
+                    password=password))
+            if 'username' not in request and username:
+                print('username={username}'.format(  # noqa: T001
+                    username=username))
             return
 
     LOGGER.warning('No mapping matched')
diff --git a/test_data/entry-name-extraction/git-pass-mapping.ini b/test_data/entry-name-extraction/git-pass-mapping.ini
@@ -0,0 +1,3 @@
+[mytest.com]
+username_extractor=entry_name
+target=dev/mytest/myuser
diff --git a/test_data/regex-extraction/git-pass-mapping.ini b/test_data/regex-extraction/git-pass-mapping.ini
@@ -0,0 +1,4 @@
+[mytest.com]
+username_extractor=regex_search
+regex_username=^myuser: (.*)$
+target=dev/mytest
diff --git a/test_data/unknown-username-extractor/git-pass-mapping.ini b/test_data/unknown-username-extractor/git-pass-mapping.ini
@@ -0,0 +1,5 @@
+[DEFAULT]
+username_extractor=doesntexist
+
+[mytest.com]
+target=dev/mytest
diff --git a/test_passgithelper.py b/test_passgithelper.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[mytest.com]`
	`2`	`+username_extractor=entry_name`
	`3`	`+target=dev/mytest/myuser`