nsa

#!/usr/bin/python3
#
# nsapass - the simplest, most usable and most secure passwords manager.
# Copyright (C) 2021 caveman
# https://github.com/al-caveman/nsapass
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

import argparse
import os
import sys
import string
import re
import json
import subprocess
import time
import datetime
import math
import secrets
import hashlib
import atexit
import getpass
import base64
import signal
import fcntl

#######################################
#                             __      #
#           configs below   <(o )___  #
#                            ( ._> /  #
#######################################

# location of ipc's named pipes
IPC_DIR = '/tmp/nsapass'

# encoding of strings
ENCODING = 'utf-8'

# location of encrypted passwords db
DATABASE_PATH = os.path.expanduser('~/.local/share/nsapass/db')

# password character sets
PASSWORD_SETS = {
    'alphanumerics' : string.ascii_letters + string.digits,
    'hexdigits'     : string.hexdigits,
}

# default passwords set
DEFAULT_SET = 'alphanumerics'

# server timeout in seconds.  0 for no timeout.
TIMEOUT = 30

# key derivation function command.  set it to None to disable it
KDF_COMMAND = {
    'COMMAND'       : ['argon2', 'nsapasssalt', '-d', '-t', '20',
                       '-k', '1048576', '-p', '4', '-r'],
    'STDIN'         : '{DATABASE_PASSWORD}',
    'TAKE_STDERR'   : False,
    'TAKE_STDOUT'   : True,
    'RETURN_VALUES' : {0:None, '*':'argon2 error'}}

# encrypt command
ENCRYPT_COMMAND = {
    'COMMAND'       : ['openssl', 'enc', '-chacha20',
                       '-out={DATABASE_PATH}', '-e',
                       '-k={DATABASE_PASSWORD}', '-iter=1'],
    'STDIN'         : '{DATABASE_DATA}',
    'TAKE_STDERR'   : False,
    'TAKE_STDOUT'   : True,
    'RETURN_VALUES' : {0:None, '*':'openssl error'}}

# decrypt command
DECRYPT_COMMAND = dict(ENCRYPT_COMMAND)
DECRYPT_COMMAND['COMMAND'] = ['openssl', 'enc', '-chacha20',
                              '-in={DATABASE_PATH}', '-d',
                              '-k={DATABASE_PASSWORD}', '-iter=1']
DECRYPT_COMMAND['STDIN'] = ''

# commands used by `nsa do -c COMMANDS`.  each command must be a single
# letter.  below is an example of defining commands to copy and paste
# various fields from the database.
template_command = {
    'COMMAND'       : ['xdotool', '-'],
    'STDIN'         : '',
    'TAKE_STDERR'   : False,
    'TAKE_STDOUT'   : False,
    'RETURN_VALUES' : {0:None, '*':'external command error'}}
DO_COMMANDS = {c:dict(template_command) for c in [
    'uri', 'user', 'pass', 'cli', 'web', 'cat']}
DO_COMMANDS['uri' ]['STDIN'] = "type '{URI}'"
DO_COMMANDS['user']['STDIN'] = "type '{USERNAME}'"
DO_COMMANDS['pass']['STDIN'] = "type '{PASSWORD}'"
DO_COMMANDS['cli' ]['STDIN'] = \
    'type "{USERNAME}"\nkey Return\ntype "{PASSWORD}"\nkey Return'
DO_COMMANDS['web' ]['STDIN'] = \
    'type "{USERNAME}"\nkey Tab\ntype "{PASSWORD}"\nkey Return'
DO_COMMANDS['cat'         ]['COMMAND'] = ['cat']
DO_COMMANDS['cat'         ]['STDIN'  ] = '{DATA}'

# theme
TIME = '%Y-%m-%d %H:%M'
COLOURS = {'RED'    : '\33[0;31m', 'BRED'   : '\33[1;31m',
           'BGRED'  : '\33[0;41m', 'YELLOW' : '\33[0;33m',
           'BGREEN' : '\33[1;32m', 'BLUE'   : '\33[0;34m',
           'GRAY'   : '\33[0;90m', 'MAGENTA': '\33[0;35m',
           'RESET'  : '\33[0m'}
FORMAT = {
    'DEBUG'       : '{MAGENTA}[debug]{RESET} {}\n',
    'INFO'        : '{BGREEN}*{RESET} {}\n',
    'WARN'        : '{YELLOW}*{RESET} {}\n',
    'ERROR'       : '{RED}[error]{RESET} {}\n',
    'PROMPT'      : '{BLUE}< {}{RESET} ',
    'PROMPTSTDIN' : '{BLUE}< {} (stdin){RESET}\n',
    'TAGS'        : '{BGREEN}{}{RESET}',
    'USERNAME'    : '{YELLOW}[{}{YELLOW}]{RESET}',
    'PASSWORD'    : '{RED}[{BGRED}{}{RED}]{RESET}',
    'DIGEST'      : '{RED}[{:.10}{RED}]{RESET}',
    'TIME'        : '{BLUE}{}{RESET}',
    'URI'         : '{MAGENTA}[{}{MAGENTA}]{RESET}',
    'NOTE'        : '{GRAY}[{}]{RESET}',
    'HIDDEN'      : '{GRAY}******{RESET}',
    'NONE'        : '',
    'ADD'         : '{BGREEN}+ {RESET}',
    'DEL'         : '{BRED}- {RESET}',
    'LIST'        : '{DIFF}{TIME} {TAGS} {USERNAME} {PASSWORD} '
                    '{DIGEST} {URI} {NOTE}\n'}

#########################################
#                                       #
#          WARNING:  DEVS ONLY          #
#                                       #
#########################################

VERSION = '10'
YEAR    = '2022'

CMD_CREATE = 'create'
CMD_CHPASS = 'chpass'
CMD_START  = 'start'
CMD_STOP   = 'stop'
CMD_DO     = 'do'
CMD_ADD    = 'add'
CMD_DEL    = 'del'
CMD_MOD    = 'mod'
CMD_LS     = 'ls'
CMD_DIFF   = 'diff'
CMD_COMMIT = 'commit'
CMD_DROP   = 'drop'

ARG_INFO        = 'v'
ARG_STDIN_INPUT = 's'
ARG_DB_PATH     = 'd'
ARG_QUERY       = 'query'
ARG_SHOWPASS    = 'z'
ARG_TAGS        = 't'
ARG_USERNAME    = 'u'
ARG_PASS_SET    = 'p'
ARG_PASS_OPT    = 'o'
ARG_PASS_BIT    = 'b'
ARG_PASS_LEN    = 'l'
ARG_PASS_MAN    = 'm'
ARG_PASS_KEY    = 'f'
ARG_URI         = 'r'
ARG_NOTE        = 'n'
ARG_COMMANDS    = 'c'
ARG_DEBUG       = 'V'
ARG_NOCOLOUR    = 'C'
ARG_IPC_DIR     = 'i'

KEY_DB_USERNAME     = 'username'
KEY_DB_PASS         = 'password'
KEY_DB_DATAB64      = 'datab64s'
KEY_DB_DIGEST       = 'digest'
KEY_DB_URI          = 'uri'
KEY_DB_NOTE         = 'note'
KEY_DB_TIME         = 'timestamp'

KEY_IPC_CMD         = 'command'
KEY_IPC_ARGS        = 'arguments'
KEY_IPC_PATH        = 'path'
KEY_IPC_REPLY_TYPE  = 'type'
KEY_IPC_REPLY_DATA  = 'data'

VAL_IPC_REPLY_TYPE_OUT      = 'out'
VAL_IPC_REPLY_TYPE_DEBUG    = 'debug'
VAL_IPC_REPLY_TYPE_INFO     = 'info'
VAL_IPC_REPLY_TYPE_WARN     = 'warn'
VAL_IPC_REPLY_TYPE_ERR      = 'err'
VAL_IPC_REPLY_TYPE_CMD      = 'command'
VAL_IPC_REPLY_TYPE_ENTRY    = 'entry'

FRMT2KEY = {'USERNAME': KEY_DB_USERNAME, 'PASSWORD': KEY_DB_PASS,
            'DATA'    : KEY_DB_DATAB64,  'DIGEST'  : KEY_DB_DIGEST,
            'URI'     : KEY_DB_URI,      'NOTE'    : KEY_DB_NOTE,
            'TIME'    : KEY_DB_TIME}
KEY2FRMT = {value:key for key, value in FRMT2KEY.items()}

enable_debug = True

def frmtstr(s, frmt, show=True):
    """formats a value"""
    if not s: s = FORMAT['NONE'].format(s, **COLOURS)
    elif not show: s = FORMAT['HIDDEN'].format(s, **COLOURS)
    return FORMAT[frmt].format(s, **COLOURS)

def frmtentry(tags, entry, showpass, diff=None):
    """formats a database entry"""
    local_time = datetime.datetime.fromtimestamp(
        entry[KEY_DB_TIME], datetime.timezone.utc).astimezone()
    values = {'DIFF': frmtstr(diff, diff) if diff else '',
              'TAGS': frmtstr(tags, 'TAGS')}
    for frmt, key in FRMT2KEY.items():
        if key == KEY_DB_DATAB64: continue
        show = showpass if key == KEY_DB_PASS else True
        s = local_time.strftime(TIME) if key == KEY_DB_TIME else entry[key]
        values[frmt] = frmtstr(s, frmt, show)
    return FORMAT['LIST'].format(**values)

def log(msg, frmt):
    """log various message types to terminal"""
    sys.stderr.write(frmt.format(msg, **COLOURS))
    sys.stderr.flush()
def debug(msg):
    if enable_debug: log(msg, FORMAT['DEBUG'])
def info(msg): log(msg, FORMAT['INFO'])
def warn(msg): log(msg, FORMAT['WARN'])
def err(msg): log(msg, FORMAT['ERROR'])

def cleanwords(words):
    """guarantee that words are single-space-separated words or None"""
    if not words: return None
    if type(words) is list: words = ' '.join(words)
    return ' '.join(words.split())

def find(db, query):
    """finds tags"""
    tags_list = list(db)
    tags_list.sort()
    query = cleanwords(query)
    if not query: return tags_list
    if query in tags_list: return [query]
    words_escaped = [re.escape(word) for word in query.split()]
    query_re = r'.*? .*?'.join(words_escaped)
    return [tags for tags in tags_list if re.search(query_re, tags)]

def askpass(name, confirm=False, stdin=False):
    """prompts users for password"""
    f = input if stdin else getpass.getpass
    prompt = 'PROMPTSTDIN' if stdin else 'PROMPT'
    pass1 = f(frmtstr(f'{name} password:', prompt))
    pass2 = pass1
    if confirm:
        pass1 = f(frmtstr(f'confirm password:', prompt))
    if pass1 == pass2:
        return pass1
    err('passwords mismatched')
    sys.exit(1)

def genpass(bits, length, letters):
    """dynamically generates passwords"""
    if length and length < 1:
        err(f'password length "{length}" is not positive')
        sys.exit(1)
    if bits:
        if bits < 1:
            err(f'password bits count "{bits}" is not positive')
            sys.exit(1)
        bits_to_length = math.ceil(bits / math.log2(len(letters)))
        if not length or bits_to_length > length: length = bits_to_length
    password = ''.join(secrets.choice(letters) for i in range(0, length))
    return password

def bin2str(data):
    """encode binary data into a string"""
    return base64.b64encode(data).decode()

def str2bin(s):
    """decode binary data from a string"""
    return base64.b64decode(s) if s else None

def readbin(path):
    """read binary data"""
    debug(f'reading binary data from "{path}"...')
    try:
        with open(path, 'rb') as f:
            debug(f'shared-locking "{path}"...')
            fcntl.lockf(f, fcntl.LOCK_SH)
            data = f.read()
    except FileNotFoundError:
        if path != '-':
            err(f'file "{path}" not found')
            sys.exit(1)
        data = sys.stdin.buffer.read()
    return data

def run(command, values):
    """run an external command"""
    debug(f'running command "{command}"')
    debug(f'command values "{values}"')
    command_formatted = [a.format(**values) for a in command['COMMAND']]
    try:
        p = subprocess.Popen(command_formatted,
            stdin   = subprocess.PIPE if command['STDIN'] else None,
            stdout  = subprocess.PIPE if command['TAKE_STDOUT'] else None,
            stderr  = subprocess.PIPE if command['TAKE_STDERR'] else None)
    except FileNotFoundError:
        err(f'command `{command_formatted[0]}` not found')
        sys.exit(1)
    except IndexError:
        err(f'command is not defined')
        sys.exit(1)
    except KeyError as e:
        err(f'command `{command_formatted[0]}` lacks key {e}')
        sys.exit(1)
    stdin = b''
    for before, field, _, _ in string.Formatter().parse(command['STDIN']):
        stdin += before.encode(ENCODING)
        if field is None: continue
        if field not in values:
            err(f'unknown command format field "{field}"')
            sys.exit(1)
        value = values[field]
        if field == 'DATA': stdin += str2bin(value)
        elif type(values[field]) is str: stdin += value.encode(ENCODING)
        elif type(values[field]) is bytes: stdin += value
        else:
            err(f'unknown command field data type "{type(part)}"')
            sys.exit(1)
    p_stdout, _ = p.communicate(input=stdin)
    debug(f'return code "{p.returncode}"')
    r = p.returncode if p.returncode in command['RETURN_VALUES'] else '*'
    return p_stdout, command['RETURN_VALUES'][r]

def kdf(password):
    """key derivation function"""
    if KDF_COMMAND:
        values = {'DATABASE_PASSWORD':password}
        password, kdf_err = run(KDF_COMMAND, values)
        if kdf_err:
            err(kdf_err)
            sys.exit(1)
        password = password.decode(ENCODING).rstrip('\n')
    debug(f'derived key "{password}"')
    return password

def load_json(path):
    """loads a json file"""
    debug(f'loading json file "{path}"...')
    if not os.path.exists(path):
        err(f'could not find file "{path}"')
        sys.exit(1)
    with open(path, 'r') as f:
        try:
            return json.load(f)
        except json.JSONDecodeError:
            err(f'failed to decode json file "{path}"')
    sys.exit(1)

def load_db(path, stdin, password=None):
    """load database"""
    debug(f'loading "{path}"...')
    if not os.path.exists(path):
        err(f'database "{path}" not found.  did you create it?')
        sys.exit(1)
    if not password:
        password = kdf(askpass('database', stdin=stdin))
    values = {'DATABASE_PATH' : path, 'DATABASE_PASSWORD' : password}
    data, err_msg = run(DECRYPT_COMMAND, values)
    if err_msg:
        err(err_msg)
        sys.exit(1)
    try:
        db = json.loads(data)
        return db, password
    except (json.JSONDecodeError, UnicodeDecodeError):
        err(f'error decoding database "{path}".  bad password?')
    sys.exit(1)

def save_db(db, path, password):
    """save database"""
    debug(f'saving to "{path}"...')
    data = json.dumps(db, indent=4)
    values = {'DATABASE_PATH'     : path,
              'DATABASE_PASSWORD' : password,
              'DATABASE_DATA'     : data}
    _, err_msg = run(ENCRYPT_COMMAND, values)
    if err_msg:
        err(err_msg)
        sys.exit(1)

def ipc_init(path):
    """prepares stuff needed for ipc"""
    dirname = os.path.dirname(path)
    if len(dirname): os.makedirs(dirname, exist_ok=True)
    try:
        debug(f'creating ipc file "{path}"...')
        os.mkfifo(path, mode=400)
    except NotImplementedError:
        err("your operating system doesn't support named pipes")
        sys.exit(1)
    except FileExistsError:
        err(f'file "{path}" exists.  delete it if not used')
        sys.exit(1)
    atexit.register(os.unlink, path)
    atexit.register(debug, f'deleting named pipe "{path}"...')

def ipc_uninit(path):
    """uninitialises ipc"""
    debug(f'deleting ipc file "{path}"...')
    atexit.unregister(os.unlink)
    os.unlink(path)

def ipc_request(path, command, rargs, stdin=False):
    """define ipc request messages"""
    return {KEY_IPC_CMD:command, KEY_IPC_ARGS:rargs, KEY_IPC_PATH:path}

def ipc_reply(reply_type, data):
    """define ipc reply messages"""
    return [{KEY_IPC_REPLY_TYPE : reply_type, KEY_IPC_REPLY_DATA : data}]
def ipc_out(message)  : return ipc_reply(VAL_IPC_REPLY_TYPE_OUT, message)
def ipc_debug(message): return ipc_reply(VAL_IPC_REPLY_TYPE_DEBUG, message)
def ipc_info(message) : return ipc_reply(VAL_IPC_REPLY_TYPE_INFO, message)
def ipc_warn(message) : return ipc_reply(VAL_IPC_REPLY_TYPE_WARN, message)
def ipc_err(message)  : return ipc_reply(VAL_IPC_REPLY_TYPE_ERR, message)
def ipc_command(values): return ipc_reply(VAL_IPC_REPLY_TYPE_CMD, values)
def ipc_entry(db, tags, showpass, diff=None):
    entry = dict(db[tags])
    if entry[KEY_DB_PASS] and not showpass: entry[KEY_DB_PASS] = '****'
    del entry[KEY_DB_DATAB64]
    return ipc_reply(VAL_IPC_REPLY_TYPE_ENTRY, (tags, entry, diff))

def ipc_do(db, last_query, rargs):
    """implements `do` sub-command"""
    args, db_keys_list = rargs
    query = args[ARG_QUERY] if args[ARG_QUERY] else last_query
    tags_list = find(db, query)
    if not tags_list: return ipc_err('nothing matched')
    if len(tags_list) > 1: return ipc_err('too many matched')
    tags = tags_list[0]
    info(f'do {FORMAT["TAGS"].format(tags, **COLOURS)}')
    replies = []
    for keys in db_keys_list:
        replies += ipc_command({k:db[tags][k] for k in keys})
    return replies

def ipc_add(db, rargs):
    """implements `add` sub-command"""
    args, password, datab64s, digest = rargs
    tags, username, uri, note, showpass = (args[k] for k in
        (ARG_TAGS, ARG_USERNAME, ARG_URI, ARG_NOTE, ARG_SHOWPASS))
    tags = cleanwords(tags)
    if tags in db: return ipc_err(f'tags "{tags}" already exists')
    info(f'add {FORMAT["TAGS"].format(tags, **COLOURS)}')
    db[tags] = {KEY_DB_USERNAME : username,
                KEY_DB_PASS     : password,
                KEY_DB_DATAB64  : datab64s,
                KEY_DB_DIGEST   : digest,
                KEY_DB_URI      : uri,
                KEY_DB_NOTE     : note,
                KEY_DB_TIME     : time.time()}
    return ipc_entry(db, tags, showpass, 'ADD')

def ipc_del(db, rargs):
    """implements `del` sub-command"""
    query, showpass = rargs[ARG_QUERY], rargs[ARG_SHOWPASS]
    tags_list = find(db, query)
    if not tags_list:
        return ipc_err('nothing matched')
    replies = []
    for tags in tags_list:
        info(f'del {FORMAT["TAGS"].format(tags, **COLOURS)}')
        replies += ipc_entry(db, tags, showpass, 'DEL')
        del db[tags]
    return replies

def ipc_mod(db, rargs):
    """implements `mod` sub-command"""
    args, password, datab64s, digest = rargs
    query, tags, username, uri, note, showpass = (args[k] for k in
        (ARG_QUERY, ARG_TAGS, ARG_USERNAME, ARG_URI, ARG_NOTE,
        ARG_SHOWPASS))
    tags = cleanwords(tags)
    tags_list = find(db, query)
    if not tags_list:
        return ipc_err('nothing matched')
    replies = []
    for cur_tags in tags_list:
        info(f'mod {FORMAT["TAGS"].format(cur_tags, **COLOURS)}')
        entry = db[cur_tags]
        replies += ipc_entry(db, cur_tags, showpass, 'DEL')
        entry[KEY_DB_TIME] = time.time()
        if username: entry[KEY_DB_USERNAME] = username
        if password: entry[KEY_DB_PASS] = password
        if datab64s:
            entry[KEY_DB_DATAB64] = datab64s
            entry[KEY_DB_DIGEST] = digest
        if uri: entry[KEY_DB_URI] = uri
        if note: entry[KEY_DB_NOTE] = note
        if tags and tags != cur_tags:
            db[tags] = db[cur_tags]
            del db[cur_tags]
            cur_tags = tags
        replies += ipc_entry(db, cur_tags, showpass, 'ADD')
    return replies

def ipc_ls(db, rargs):
    """implements `ls` sub-command"""
    query, showpass = rargs[ARG_QUERY], rargs[ARG_SHOWPASS]
    formatted_query = FORMAT['TAGS'].format(' '.join(query), **COLOURS)
    info(f'ls {formatted_query}')
    tags_list = find(db, query)
    if not tags_list: return ipc_err('nothing matched')
    replies = []
    for tags in tags_list:
        replies += ipc_entry(db, tags, showpass)
    return replies

def ipc_diff(db_tmp, path_orig, password, password_orig, rargs):
    """implements `diff` sub-command"""
    info('diff')
    showpass = rargs[ARG_SHOWPASS]
    db_orig, _ = load_db(path_orig, False, password_orig)
    replies = []
    for tags in db.keys() - db_orig.keys():
        replies += ipc_entry(db, tags, showpass, 'ADD')
    for tags in db_orig.keys() - db.keys():
        replies += ipc_entry(db_orig, tags, showpass, 'DEL')
    for tags in db.keys() & db_orig.keys():
        if [k for k in db[tags] if db[tags][k] != db_orig[tags][k]]:
            replies += ipc_entry(db_orig, tags, showpass, 'DEL')
            replies += ipc_entry(db, tags, showpass, 'ADD')
    if password != password_orig:
        passfrmt = frmtstr(password, 'PASSWORD', showpass)
        replies += ipc_warn(f'updated database password to {passfrmt}')
    return replies

def handler_sigint(signum, frame):
    """pretty interrupt handling"""
    info('received interrupt.  exiting...')
    sys.exit(0)

def handler_sigalrm(signum, frame):
    """suspend server upon timeout"""
    info('server timed out.  suspending...')
    ipc_uninit(ipc_server_path)
    getpass.getpass(frmtstr('hit enter to resume the server', 'PROMPT'))
    ipc_init(ipc_server_path)
    info('server resumed')
    signal.alarm(TIMEOUT)

# parse arguments
cmdname = os.path.basename(sys.argv[0])
allcmds = [
    [CMD_CREATE, [ARG_DB_PATH, ARG_STDIN_INPUT],
        {'help':"create a databases"}],
    [CMD_CHPASS, [ARG_STDIN_INPUT],
        {'help':"change databases's password"}],
    [CMD_START, [ARG_STDIN_INPUT, ARG_DB_PATH],
        {'help':'starts nsapass'}],
    [CMD_STOP, [ARG_STDIN_INPUT],
        {'help':'stops nsapass and discards any uncommitted changes'}],
    [CMD_DO , [ARG_QUERY, ARG_STDIN_INPUT, ARG_COMMANDS],
        {'help':'do things (e.g. type passwords)'}],
    [CMD_ADD, [ARG_TAGS, ARG_USERNAME, ARG_PASS_SET, ARG_PASS_OPT,
        ARG_PASS_BIT, ARG_PASS_LEN, ARG_PASS_MAN, ARG_PASS_KEY, ARG_URI,
        ARG_NOTE, ARG_STDIN_INPUT, ARG_SHOWPASS], {'help':'add an entry'}],
    [CMD_DEL, [ARG_QUERY, ARG_STDIN_INPUT, ARG_SHOWPASS],
        {'help':'delete an entry'}],
    [CMD_MOD, [ARG_QUERY, ARG_TAGS, ARG_USERNAME, ARG_PASS_SET,
        ARG_PASS_OPT, ARG_PASS_BIT, ARG_PASS_LEN, ARG_PASS_MAN,
        ARG_PASS_KEY, ARG_URI, ARG_NOTE, ARG_STDIN_INPUT, ARG_SHOWPASS],
        {'help':'modify an entry'}],
    [CMD_LS, [ARG_QUERY, ARG_STDIN_INPUT, ARG_SHOWPASS],
        {'help':'view entries'}],
    [CMD_DIFF, [ARG_STDIN_INPUT, ARG_SHOWPASS],
        {'help':'show modifications done so far'}],
    [CMD_COMMIT, [ARG_STDIN_INPUT],
        {'help':'commit changes to the database'}],
    [CMD_DROP, [ARG_STDIN_INPUT],
        {'help':'discard all uncommitted changed'}],
]
allargs = {
    ARG_QUERY   : {'metavar':'QUERY', 'type':str, 'nargs':'*',
                    'help':'query tags'},
    ARG_TAGS    : {'metavar':'TAG', 'type':str, 'nargs':'+',
                    'help':"new tags"},
    ARG_USERNAME: {'metavar':'USERNAME', 'type':str,
                    'help':'new username'},
    ARG_PASS_SET: {'metavar':'SET', 'type':str, 'default':DEFAULT_SET,
                    'help':'pre-defined password letters set name'},
    ARG_PASS_OPT: {'metavar':'LETTERS', 'type':str,
                    'help':'raw password letter options'},
    ARG_PASS_BIT: {'metavar':'BIT', 'type':int,
                    'help':'generate BIT-entropy password from SET'},
    ARG_PASS_LEN: {'metavar':'LEN', 'type':int,
                    'help':'generate LEN-long password from SET'},
    ARG_PASS_MAN: {'action':'store_true', 'help':'user-defined password'},
    ARG_PASS_KEY: {'metavar':'PATH', 'type':str,
                    'help':'data file in PATH, or STDIN if "-"'},
    ARG_URI     : {'metavar':'URI', 'type':str,
                    'help':"a uniform resource identifier"},
    ARG_NOTE    : {'metavar':'NOTE', 'type':str, 'help':"a note"},
    ARG_COMMANDS: {'metavar':'COMMANDS', 'type':str, 'nargs':'+',
                    'default':[], 'help': f"""perform actions specified in
                    COMMANDS in order from left to right.  COMMANDS are
                    defined in option DO_COMMANDS, which currently are:
                    {', '.join(list(DO_COMMANDS))}"""},
    ARG_SHOWPASS    : {'action':'store_true', 'help':'show passwords'},
    ARG_STDIN_INPUT : {'action':'store_true', 'help':'input from stdin'},
    ARG_DB_PATH     : {'metavar':'DB', 'type':str,
                        'help':'set database path'}}
parser = argparse.ArgumentParser()
parser.add_argument('-' + ARG_INFO, action='store_true',
                    help='show information about nsapass')
parser.add_argument('-' + ARG_DEBUG, action='store_true',
                    help='show debugging information')
parser.add_argument('-' + ARG_NOCOLOUR, action='store_true',
                    help='disable colourful output')
parser.add_argument('-' + ARG_IPC_DIR, metavar='DIR', type=str,
                    help='ipc directory')
subparsers = parser.add_subparsers(title='commands', dest='command')
for cmd_name, cmd_args, cmd_named in allcmds :
    subp = subparsers.add_parser(cmd_name, **cmd_named)
    for arg in cmd_args:
        arg_prefix = '-' if len(arg) == 1 else ''
        subp.add_argument(arg_prefix + arg, **allargs[arg])
args = parser.parse_args()

# some usability stuff
if args.v:
    sys.stdout.write(
     f"nsapass v{VERSION}  copyright (C) {YEAR}  caveman\n"
     "https://github.com/Al-Caveman/nsapass\n\n"
     "this program comes with ABSOLUTELY NO WARRANTY; for details\n"
     "read https://github.com/Al-Caveman/nsapass/blob/master/LICENSE\n")
    sys.exit()
if args.command is None:
    parser.print_help()
    sys.exit()
enable_debug = args.V
if args.C:
    for c in COLOURS: COLOURS[c] = ''
if args.i: IPC_DIR = args.i
ipc_server_path = f'{IPC_DIR}/server'

# register signal handlers
signal.signal(signal.SIGINT, handler_sigint)
signal.signal(signal.SIGTERM, handler_sigint)
signal.signal(signal.SIGALRM, handler_sigalrm)

# starts the server loop
if args.command == CMD_START:
    ipc_init(ipc_server_path)
    path = args.d if args.d else DATABASE_PATH
    path_tmp = path + '.temp'
    if os.path.exists(path_tmp):
        warn(f'found uncommitted changes from a previous session in "{path_tmp}"')
        warn(f're-loading the uncommitted changes...')
        db, password = load_db(path_tmp, args.s)
        warn(f'execute:')
        warn(f'  `{cmdname} {CMD_DIFF}` to see the uncommitted changes')
        warn(f'  `{cmdname} {CMD_COMMIT}` to commit them')
        warn(f'  `{cmdname} {CMD_DROP}` to discard them')
    else:
        db, password = load_db(path, args.s)
    password_orig = password
    last_do_query = None
    info('waiting for ipc commands...')
    while True:  # runs indefinitely until stopped by SIGINT or `CMD_STOP`
        signal.alarm(TIMEOUT)
        request = load_json(ipc_server_path)
        rcmd = request[KEY_IPC_CMD]
        rargs = request[KEY_IPC_ARGS]
        client_ipc_path = request[KEY_IPC_PATH]
        debug(f'got ipc request {rcmd} {rargs}')

        # implement nsapass's sub-commands
        replies = []
        if rcmd == CMD_CHPASS:
            info('updating database password...')
            password = kdf(rargs)
            save_db(db, path_tmp, password)
            replies += ipc_info(
                    'database password change staged')
        elif rcmd == CMD_DO :
            if rargs[0][ARG_QUERY]: last_do_query = rargs[0][ARG_QUERY]
            replies += ipc_do(db, last_do_query, rargs)
        elif rcmd == CMD_ADD:
            replies += ipc_add(db, rargs)
            save_db(db, path_tmp, password)
        elif rcmd == CMD_DEL:
            replies += ipc_del(db, rargs)
            save_db(db, path_tmp, password)
        elif rcmd == CMD_MOD:
            replies += ipc_mod(db, rargs)
            save_db(db, path_tmp, password)
        elif rcmd == CMD_LS :
            replies += ipc_ls(db, rargs)
        elif rcmd == CMD_DIFF:
            replies += ipc_diff(db, path, password, password_orig, rargs)
        elif rcmd == CMD_COMMIT:
            if not os.path.exists(path_tmp):
                replies += ipc_warn('no changes to commit')
            else:
                debug(f'moving "{path_tmp}" to "{path}"...')
                os.rename(path_tmp, path)
                replies += ipc_info(f'changes committed to "{path}"')
        elif rcmd == CMD_DROP:
            if not os.path.exists(path_tmp):
                replies += ipc_warn('no changes to drop')
            else:
                db, _ = load_db(path, False, password_orig)
                debug(f'deleting "{path_tmp}"...')
                os.unlink(path_tmp)
                replies += ipc_info(f'changes dropped')

        # write replies back to client
        debug(f'writing to "{client_ipc_path}" ipc reply {replies}...')
        try:
            with open(client_ipc_path, 'w') as f:
                debug(f'exclusive-locking "{client_ipc_path}"...')
                fcntl.lockf(f, fcntl.LOCK_EX)
                json.dump(replies, f)
        except BrokenPipeError:
            err("client's pipe is broken")

        # stop nsapass
        if rcmd == CMD_STOP:
            info(f'stop')
            sys.exit()

# create nsapass passwords database
if args.command == CMD_CREATE:
    path = args.d if args.d else DATABASE_PATH
    if os.path.exists(path):
        err(f'database "{path}" already exists')
        sys.exit(1)
    password = kdf(askpass('new database', confirm=True, stdin=args.s))
    save_db({}, path, password)
    info(f'database created in "{path}"')
    sys.exit(0)

# define values needed for various commands
if args.command == CMD_CHPASS:
    new_db_pass = askpass('new database', confirm=True, stdin=args.s)
elif args.command in {CMD_ADD, CMD_MOD}:
    password, datab64s, digest = None, None, None
    if args.p not in PASSWORD_SETS:
        err(f'set "{args.p}" is not among: {", ".join(PASSWORD_SETS)}')
        sys.exit(1)
    letters = args.o if args.o else PASSWORD_SETS[args.p]
    if args.b or args.l: password = genpass(args.b, args.l, letters)
    if args.m: password = askpass('new entry', confirm=True, stdin=args.s)
    if args.f:
        data = readbin(args.f)
        datab64s = bin2str(data)
        digest = hashlib.sha224(data).hexdigest()
elif args.command == CMD_DO:
    db_keys_list = []
    for command in args.c:
        frmt = ''.join(DO_COMMANDS[command]['COMMAND'])
        frmt += DO_COMMANDS[command]['STDIN']
        keys = []
        for _, field, _, _ in string.Formatter().parse(frmt):
            if field is None: continue
            if field not in FRMT2KEY:
                err(f'unknown do format field "{field}"')
                sys.exit(1)
            keys.append(FRMT2KEY[field])
        db_keys_list.append(keys)

# terminate useless cases early on
if args.command == CMD_ADD and not args.t:
    err('tags are required')
    sys.exit(1)
if args.command == CMD_DO and args.c:
    unknown_commands = list(set(args.c) - DO_COMMANDS.keys())
    if unknown_commands:
        err(f'unknown do commands: {", ".join(unknown_commands)}')
        sys.exit(1)

# prepare things to talk to server
ipc_client_path = f'{IPC_DIR}/client.{os.getpid()}'
ipc_init(ipc_client_path)
if args.command == CMD_CHPASS: rargs = new_db_pass
elif args.command in {CMD_ADD, CMD_MOD}:
    rargs = [vars(args), password, datab64s, digest]
elif args.command == CMD_DO: rargs = [vars(args), db_keys_list]
else: rargs = vars(args)
request = ipc_request(ipc_client_path, args.command, rargs)

# send ipc request
debug(f'sending ipc request: {request}')
try:
    fd = os.open(ipc_server_path, os.O_WRONLY | os.O_NONBLOCK)
    fcntl.lockf(fd, fcntl.LOCK_EX)
    os.write(fd, json.dumps(request).encode(ENCODING))
    os.close(fd)
except OSError:
    err(f'"{ipc_server_path}" not found.  nsapass stopped or suspended?')
    sys.exit(1)
except BrokenPipeError:
    err("server's pipe is broken")
    sys.exit(1)

# processing server's ipc replies
debug(f'waiting for ipc replies...')
replies = load_json(ipc_client_path)
debug(f'got replies: {replies}')
command_i = 0
for reply in replies:
    reply_type = reply[KEY_IPC_REPLY_TYPE]
    reply_data = reply[KEY_IPC_REPLY_DATA]
    if reply_type == VAL_IPC_REPLY_TYPE_CMD:
        command = args.c[command_i]
        command_i += 1
        values = {KEY2FRMT[key]:value for key, value in reply_data.items()}
        stdout, err_msg = run(DO_COMMANDS[command], values)
        if stdout: sys.stdout.write(stdout)
        if err_msg:
            err(err_msg)
            sys.exit(1)
        continue
    fout = sys.stdout.write
    if reply_type == VAL_IPC_REPLY_TYPE_DEBUG  : fout = debug
    elif reply_type == VAL_IPC_REPLY_TYPE_INFO : fout = info
    elif reply_type == VAL_IPC_REPLY_TYPE_WARN : fout = warn
    elif reply_type == VAL_IPC_REPLY_TYPE_ERR  : fout = err
    elif reply_type == VAL_IPC_REPLY_TYPE_ENTRY:
        tags, entry, diff = reply_data
        reply_data = frmtentry(tags, entry, args.z, diff)
    fout(reply_data)