sally 1.0.5__py3-none-any.whl

sally/__init__.py

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+"""
+SALLY
+sally package
+
+"""
+
+__version__ = '1.0.5'  # also change in setup.py
+
+import logging
+
+from hio.help import ogling
+
+from sally.app.logs import TruncatedFormatter
+
+log_name = 'sally'  # name of this project that shows up in log messages
+log_format_str = f'%(asctime)s [{log_name}] %(levelname)-8s %(module)s.%(funcName)s-%(lineno)s %(message)s'
+
+ogler = ogling.initOgler(prefix=log_name, syslogged=False)
+ogler.level = logging.INFO
+
+formatter = TruncatedFormatter(log_format_str)
+formatter.default_msec_format = None
+logHandler = logging.StreamHandler()
+logHandler.setFormatter(formatter)
+ogler.baseFormatter = formatter
+ogler.baseConsoleHandler = logHandler
+ogler.baseConsoleHandler.setFormatter(formatter)
+ogler.reopen(name=log_name, temp=True, clear=True)
+
+def set_log_level(loglevel, logger):
+    """Set the log level for the logger."""
+    ogler.level = logging.getLevelName(loglevel.upper())
+    logger.setLevel(ogler.level)

sally/app/__init__.py

@@ -0,0 +1,7 @@
+# -*- encoding: utf-8 -*-
+
+"""
+KERI
+sally.app package
+
+"""

sally/app/bootstrapping.py

@@ -0,0 +1,82 @@
+from typing import Callable
+
+from hio.base import doing
+from keri.app import habbing, oobiing
+
+from sally import ogler, log_name
+
+logger = ogler.getLogger(log_name)
+
+
+class BootstrapRunner(doing.DoDoer):
+    def __init__(self, hby: habbing.Habery, tymth: Callable):
+        """
+        Parameters:
+            hby (Habery): the hab in which to create the AID, if needed
+            tymth (function): the clock time (scheduler tick rate) to use from the parent Doist
+        """
+        self.hby = hby
+        self.complete = False
+        super(BootstrapRunner, self).__init__(tymth=tymth)
+        self.extend([OobiResolveBootstrapper(hby, self)])
+
+    def recur(self, tyme, deeds=None):
+        if self.complete:
+            return True
+        super(BootstrapRunner, self).recur(tyme, deeds)
+        return False
+
+    def configureAndIncept(self):
+        """Configure a keystore by resolving OOBIs in config"""
+        self.extend(OobiResolveBootstrapper(self.hby, self))
+
+class OobiResolveBootstrapper(doing.Doer):
+    """
+    Bootstraps OOBI Resolutions for a Habery and an AID, resolving all OOBIs in the bootstrap configuration file.
+    """
+
+    def __init__(self, hby: habbing.Habery, parent: BootstrapRunner, tock=0.0, **kwa):
+        self.hby = hby
+        self.parent = parent
+        super(OobiResolveBootstrapper, self).__init__(tock=tock, **kwa)
+
+    def configure_and_incept(self):
+        oobi_count = self.hby.db.oobis.cntAll()
+        if oobi_count:
+            obi = oobiing.Oobiery(hby=self.hby)
+            self.parent.extend(obi.doers)
+
+            while oobi_count > self.hby.db.roobi.cntAll():
+                yield 0.25
+
+            for (oobi,), obr in self.hby.db.roobi.getItemIter():
+                if obr.state in (oobiing.Result.resolved,):
+                    logger.info(f"{oobi} succeeded")
+                if obr in (oobiing.Result.failed,):
+                    logger.error(f"{oobi} failed")
+
+            self.parent.remove(obi.doers)
+
+        wc = [oobi for (oobi,), _ in self.hby.db.woobi.getItemIter()]
+        if len(wc) > 0:
+            logger.info(f"\nAuthenticating Well-Knowns...")
+            authn = oobiing.Authenticator(hby=self.hby)
+            self.parent.extend(authn.doers)
+
+            while True:
+                cap = []
+                for (_,), wk in self.hby.db.wkas.getItemIter(keys=b''):
+                    cap.append(wk.url)
+
+                if set(wc) & set(cap) == set(wc):
+                    break
+
+                yield 0.5
+
+            self.parent.remove(authn.doers)
+
+        self.parent.complete = True
+
+    def recur(self, tock=0.0, **opts):
+        yield from self.configure_and_incept()
+        return True

sally/app/cli/__init__.py

@@ -0,0 +1,7 @@
+# -*- encoding: utf-8 -*-
+
+"""
+KERI
+sally.app.cli package
+
+"""

sally/app/cli/commands/__init__.py

@@ -0,0 +1,7 @@
+# -*- encoding: utf-8 -*-
+
+"""
+KERI
+sally.app.cli.commands package
+
+"""

sally/app/cli/commands/hook/demo.py

@@ -0,0 +1,120 @@
+# -*- encoding: utf-8 -*-
+"""
+sally.cli.commands module
+
+"""
+import argparse
+import logging
+import pprint
+
+import falcon
+from hio.core import http
+from keri import help
+from keri.app import directing
+
+from sally import log_name, ogler
+from sally.core import handling, httping
+from sally.core.monitoring import HealthEnd
+
+logger = ogler.getLogger(log_name)
+
+parser = argparse.ArgumentParser(description='Launch SALLY sample web hook server')
+parser.set_defaults(handler=lambda args: launch(args),
+                    transferable=True)
+parser.add_argument('-p', '--http',
+                    action='store',
+                    default=9923,
+                    help="Port on which to listen for web hook events.  Defaults to 9923")
+
+
+def launch(args, expire=0.0):
+    baseFormatter = logging.Formatter('%(asctime)s [hook] %(levelname)-8s %(message)s')
+    baseFormatter.default_msec_format = None
+    help.ogler.baseConsoleHandler.setFormatter(baseFormatter)
+    help.ogler.level = logging.getLevelName(logging.INFO)
+    help.ogler.reopen(name="hook", temp=True, clear=True)
+
+    httpPort = args.http
+
+    app = falcon.App(
+        middleware=httping.cors_middleware())
+    app.add_route("/", WebhookListener())
+    app.add_route("/health", HealthEnd())
+
+    server = http.Server(port=httpPort, app=app)
+    httpServerDoer = http.ServerDoer(server=server)
+
+    logger.info(f"Sally Web Hook Sample listening on {httpPort}")
+    directing.runController(doers=[httpServerDoer], expire=expire)
+
+
+class WebhookListener:
+    """
+    Demonstration endpoint for web hook calls that prints events to stdout and stores a simple presentation cache.
+    """
+    def __init__(self):
+        self.received = dict()
+
+    def on_post(self, req, resp):
+        """Receives web hook POST events by printing the credential results to stdout and storing presentations them in memory
+        Parameters:
+            req: falcon.Request HTTP request
+            rep: falcon.Response HTTP response
+        """
+        logger.info("** HEADERS **")
+        logger.info(pprint.pprint(req.headers))
+        logger.info("*************")
+
+        logger.info("**** BODY ****")
+        body = req.get_media()
+        logger.info(pprint.pprint(body))
+        logger.info("**************")
+
+        data = body.get("data", {})
+        if not data:
+            logger.error("No data in body")
+            resp.media = {"error": "No data in body"}
+            resp.status = falcon.HTTP_400
+            return
+        type = self._resolve_type(data["schema"])
+
+        holder = data.get("recipient", "")
+        presentation = dict(
+            credential=data.get("credential", ""),
+            type=type,
+            issuer=body.get("actor", ""),
+            holder=holder,
+            LEI=data.get("LEI", ""),
+            personLegalName=data.get("personLegalName", ""),
+            officialRole=data.get("officialRole", ""),
+        )
+        self.received[holder] = presentation
+        resp.status = falcon.HTTP_202
+
+    def _resolve_type(self, schema_said):
+        """Return human friendly name for schema type"""
+        match schema_said:
+            case handling.QVI_SCHEMA:
+                return "QVI"
+            case handling.LE_SCHEMA:
+                return "LE"
+            case handling.OOR_AUTH_SCHEMA:
+                return "OOR Auth"
+            case handling.OOR_SCHEMA:
+                return "OOR"
+            case _:
+                raise ValueError(f"Unknown schema type with SAID: {schema_said}")
+
+    def on_get(self, req, resp):
+        """
+        Tells the presenter if they have presented a credential before.
+        Used in testing to determine that a presentation has succeeded.
+        """
+        holder = req.get_param("holder", required=True)
+        if holder in self.received:
+            resp.media = self.received[holder]
+            resp.status = falcon.HTTP_200
+        else:
+            resp.media = {"error": f"No credential presented by {holder}"}
+            resp.status = falcon.HTTP_404
+

sally/app/cli/commands/server/start.py

@@ -0,0 +1,134 @@
+# -*- encoding: utf-8 -*-
+"""
+sally.cli.commands module
+
+"""
+import argparse
+import os
+
+from hio.base import doing
+from keri.app import keeping, habbing, configing
+from keri.app.cli.common import existing
+
+import sally
+from sally import ogler, log_name, set_log_level
+from sally.app.bootstrapping import BootstrapRunner
+from sally.core import serving
+
+parser = argparse.ArgumentParser(description='Launch Sally vLEI credential presentation receiver service.')
+parser.set_defaults(handler=lambda args: launch(args),
+                    transferable=True)
+
+parser.add_argument(
+    "-d", "--direct", action="store_true", default=False,
+    help="Listen for direct-mode messages on HTTP port.  Default is True")
+parser.add_argument(
+    '-p', '--http', action='store', default=9723,
+    help="Port on which to listen for OOBI requests.  Defaults to 9723")
+parser.add_argument(
+    '-n', '--name', action='store', default="sally",
+    help="Name of controller. Default is sally.")
+parser.add_argument(
+    '-b', '--base', required=False, default="",
+    help='additional optional prefix to file location of KERI keystore')
+parser.add_argument(
+    "-c", "--config-dir", dest="configDir",
+    help="directory override for configuration data")
+parser.add_argument(
+    "-f", '--config-file', dest="configFile", action='store', default=None,
+    help="Habery (keystore) configuration filename")
+parser.add_argument(
+    "-i", "--incept-file", dest="inceptFile", action='store', default=None,
+    help="inception configuration filename")
+parser.add_argument(
+    '-a', '--alias', required=True,
+    help='human readable alias for the new identifier prefix')
+parser.add_argument(
+    '-s', '--salt', required=False,
+    help='qualified base64 salt for creating key pairs')
+parser.add_argument(
+    '--passcode', dest="bran", default=None,
+    help='21 character encryption passcode for keystore (is not saved)')
+parser.add_argument(
+    '-w', '--web-hook', action='store', required=True, default=None,
+    help='Webhook address for outbound notifications of credential issuance or revocation')
+parser.add_argument(
+    '--auth', action="store", required=True,
+    help='AID or alias of authority for OOBIs and QVI credential issuer')
+parser.add_argument(
+    "-r", "--retry-delay", default=10, type=int, action="store",
+    help="retry delay (in seconds) for failed web hook attempts")
+parser.add_argument(
+    "-e", "--escrow-timeout", default=10, type=int, action="store",
+    help="timeout (in minutes) for escrowed events that have not been delivered to the web hook.  Defaults to 10")
+parser.add_argument(
+    "-l", "--loglevel", action="store", required=False, default=os.getenv("SALLY_LOG_LEVEL", "INFO"),
+    help="Set log level to DEBUG | INFO | WARNING | ERROR | CRITICAL. Default is CRITICAL")
+
+
+logger = ogler.getLogger(log_name)
+
+def launch(args, expire=0.0):
+    """Launch Sally vLEI credential presentation receiver service"""
+    # Logging config
+    set_log_level(args.loglevel, logger)
+
+    # Parse arguments
+    hook = args.web_hook
+    name = args.name
+    salt = args.salt
+    base = args.base
+    bran = args.bran
+    try:
+        http_port = int(args.http)
+    except ValueError:
+        raise ValueError(f"Invalid port number: {args.http}. Must be an integer.")
+    auth = args.auth
+    direct = args.direct
+
+    timeout = args.escrow_timeout
+    retry = args.retry_delay
+
+    alias = args.alias
+    config_file = args.configFile
+    config_dir = args.configDir
+
+    # Inception configuration for when Sally bootstraps itself
+    incept_file = args.inceptFile
+    incept_args = {
+        "name": name, "base": base, "alias": alias, "bran": bran,
+        "incept_file": incept_file, "config_dir": config_dir
+    }
+
+    hby = init_habery(name=name, base=base, bran=bran, config_file=config_file,
+                      config_dir=config_dir, salt=salt)
+    hab = serving.incept_if_new(hby, alias, incept_args)
+
+    # setup doers
+    doers = serving.setupDoers(hby, hab, alias=alias, http_port=http_port, hook=hook, auth=auth,
+                           timeout=timeout, retry=retry, direct=direct, incept_args=incept_args)
+    logger.info(f"Sally Server v{sally.__version__} listening on {http_port} with DB version {hby.db.version}")
+    serving.run_doers(doers)
+
+def init_habery(name, base, bran, config_file, config_dir, salt):
+    """Initialize or reopen the Habery (keystore)"""
+    ks = keeping.Keeper(name=name, base=base, temp=False, reopen=True)
+    aeid = ks.gbls.get('aeid')
+
+    cf = None
+    if aeid is None:
+        if config_file is not None:
+            cf = configing.Configer(name=config_file, base=base, headDirPath=config_dir,
+                                    temp=False, reopen=True, clear=False)
+        habery_cfg = dict()
+        habery_cfg["salt"] = salt if salt else None # When None causes Habery to randomize salt
+        hby = habbing.Habery(name=name, base=base, bran=bran, cf=cf, ks=ks, **habery_cfg)
+    else:
+        ks.close() # existing.setupHby reopens, so close here to avoid LMDB conflict.
+        hby = existing.setupHby(name=name, base=base, bran=bran)
+
+    # Resolve OOBIs for the Habery and the new Hab
+    bootstrap_doist = doing.Doist(limit=30.0, tock=0.03125, real=True)
+    runner = BootstrapRunner(hby=hby, tymth=bootstrap_doist.tymen())
+    bootstrap_doist.do(doers=[runner])
+    return hby

sally/app/cli/commands/version.py

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+"""
+sally.app.cli.commands module
+"""
+import argparse
+
+from hio.base import doing
+from keri.app import directing
+
+import sally
+from keri.app.cli.common import existing
+
+parser = argparse.ArgumentParser(description='Print version of sally CLI')
+parser.set_defaults(handler=lambda args: handler(args))
+parser.add_argument('--name', '-n', help='keystore name and file location of KERI keystore', required=False,
+                    default=None)
+parser.add_argument('--base', '-b', help='additional optional prefix to file location of KERI keystore',
+                    required=False, default="")
+parser.add_argument('--passcode', '-p', help='22 character encryption passcode for keystore (is not saved)',
+                    dest="bran", default=None)  # passcode => bran
+
+
+def handler(args):
+    kwa = dict(args=args)
+    doers = [doing.doify(version, **kwa)]
+    directing.runController(doers=doers, expire=0.0)
+
+
+def version(tymth, tock=0.0, **opts):
+    """ Command line version handler
+    """
+    _ = (yield tock)
+
+    args = opts["args"]
+    name = args.name
+    base = args.base
+    bran = args.bran
+
+    print(f"Library version: {sally.__version__}")
+
+    if name is not None:
+        with existing.existingHby(name=name, base=base, bran=bran) as hby:
+            print(f"Database version: {hby.db.version}")

sally/app/cli/kli.py

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+"""
+sally.app.commands module
+
+"""
+import os
+
+import multicommand
+
+from sally.app.cli import commands
+
+
+def main():
+    parser = multicommand.create_parser(commands)
+    args = parser.parse_args()
+
+    if not hasattr(args, 'handler'):
+        parser.print_help()
+        return
+
+    try:
+        args.handler(args)
+    except Exception as ex:
+        if os.getenv('DEBUG_KLI'):
+            import traceback
+            traceback.print_exc()
+        else:
+            print(f"ERR: {ex}")
+        return -1
+
+
+if __name__ == "__main__":
+    main()

sally/app/logs.py

@@ -0,0 +1,33 @@
+import copy
+import logging
+
+
+class TruncatedFormatter(logging.Formatter):
+    """
+    Formats log records with shorter module and function names and a right justified line number for readability.
+
+    Example:
+        "2025-09-05 13:59:29 [keria] INFO     serving    .runAgency       -  145 The Agency is loaded and waiting for requests..."
+    """
+
+    def __init__(self, fmt=None, datefmt=None, style='%'):
+        super().__init__(fmt, datefmt, style)
+
+    def format(self, record):
+        """
+        Format the log record with truncated module and function names.
+        Ignores exceptions and logs an error if formatting fails.
+        """
+        record = copy.copy(record)
+
+        # Truncate module and funcName to first 'chars' characters
+        mod_chars = 10  # number of spaces to truncate to
+        fn_chars = 14  # number of spaces to truncate to
+        record.module = (record.module[:mod_chars] + ' ' * mod_chars)[:mod_chars]
+        record.funcName = (record.funcName[:fn_chars] + ' ' * fn_chars)[:fn_chars]
+        record.lineno = str(record.lineno).rjust(5)  # Ensure line number is right-aligned
+        try:
+            return super().format(record)
+        except Exception as e:
+            logging.error(f'Error formatting log record: {e}')
+            raise e

sally/core/basing.py

@@ -0,0 +1,102 @@
+# -*- encoding: utf-8 -*-
+"""
+SALLY
+sally.core.basing module
+
+Database support
+"""
+from keri.core import coring, serdering
+from keri.db import dbing, subing
+
+from sally import log_name, ogler
+
+logger = ogler.getLogger(log_name)
+
+class CueBaser(dbing.LMDBer):
+    """
+    Noter stores Notifications generated by the agent that are
+    intended to be read and dismissed by the controller of the agent.
+
+    """
+    TailDirPath = "sally/db"
+    AltTailDirPath = ".sally/db"
+    TempPrefix = "sally_db_"
+
+    def __init__(self, name="cb", headDirPath=None, reopen=True, **kwa):
+        """
+
+        Parameters:
+            headDirPath:
+            perm:
+            reopen:
+            kwa:
+        """
+        self.snd = None
+
+        self.iss = None
+        self.rev = None
+
+        self.recv = None
+        self.revk = None
+
+        self.ack = None
+
+        super(CueBaser, self).__init__(name=name, headDirPath=headDirPath, reopen=reopen, **kwa)
+
+    def reopen(self, **kwa):
+        """
+
+        :param kwa:
+        :return:
+        """
+        super(CueBaser, self).reopen(**kwa)
+
+        # Database of senders of the presentation or revocation messages
+        self.snd = subing.CesrSuber(db=self, subkey='snd.', klas=coring.Prefixer)
+
+        # Presentations waiting for the grant's embedded ACDC and TEL state to
+        # finish verification.
+        self.iss = subing.CesrSuber(db=self, subkey='iss.', klas=coring.Dater)
+        # revocations that are waiting for the TEL event to be received and processed
+        self.rev = subing.CesrSuber(db=self, subkey='rev.', klas=coring.Dater)
+
+        # presentations with resolved credentials that need to be sent to the hook
+        self.recv = subing.SerderSuber(db=self, subkey="recv", klas=serdering.SerderACDC)
+        # revocations whose TEL rev event has been resolved that need to be sent to the hook
+        self.revk = subing.SerderSuber(db=self, subkey="revk", klas=serdering.SerderACDC)
+
+        # presentations that have been sent to the hook that need to be ack'ed
+        self.ack = subing.SerderSuber(db=self, subkey="ack", klas=serdering.SerderACDC)
+
+        return self.env
+
+    def clearEscrows(self):
+        """
+        Clear all credential escrows. Useful in testing to avoid many unneeded log messages or force reprocessing of presentations.
+        """
+        self.iss.trim()
+        self.rev.trim()
+        self.recv.trim()
+        self.revk.trim()
+        self.ack.trim()
+        logger.info("Cleared iss and rev escrows")
+
+    def getCounts(self):
+        """
+        Get counts of each database for metrics monitoring
+        """
+        snd  = len([said for (said,), prefixer in self.snd.getItemIter()])
+        iss  = len([said for (said,), dater in self.iss.getItemIter()])
+        rev  = len([said for (said,), dater in self.rev.getItemIter()])
+
+        recv = len([said for (said, dater_qb64), creder in self.recv.getItemIter()])
+        revk = len([said for (said, dater_qb64), creder in self.revk.getItemIter()])
+        ack  = len([said for (said,), creder in self.ack.getItemIter()])
+        return {
+            'senders': snd,
+            'iss': iss,
+            'rev': rev,
+            'recv': recv,
+            'revk': revk,
+            'ack': ack
+        }

sally/core/credentials.py

@@ -0,0 +1,59 @@
+from hio.base import doing
+from hio.help import decking
+from keri.core import coring
+
+from sally import ogler, log_name
+
+logger = ogler.getLogger(log_name)
+
+
+class TeveryCuery(doing.Doer):
+    """
+    Processes credential revocation cues and records when a given credential was revoked in the local cue database (CueBaser).
+    """
+
+    def __init__(self, cdb, reger, cues=None, **kwa):
+        """
+        Parameters:
+            cdb (CueBaser): instance of CueBaser database
+            reger (Reger): Stores ACDC / TEL events
+            cues (Deck): collection of events (cue) to process
+        """
+        self.cdb = cdb
+        self.reger = reger
+        self.cues = cues if cues is not None else decking.Deck()
+
+        super(TeveryCuery, self).__init__(**kwa)
+
+    def do(self, tymth, *, tock=0.0, **opts):
+        """
+        Iterates over the cues Deck and processes each ACDC revocation cue to save the ACDC sender and revocation time in the cue database.
+
+        Inherited Parameters:
+            tymth (function): closure for read only injection of cycle time in seconds
+            tock (float): cycle time in seconds
+        """
+        self.wind(tymth)  # Set the clock with cycle time function
+        self.tock = tock  # Set the cycle time of this doer
+        yield self.tock   # allow priming of this doer to advance to this line
+
+        while True:
+            while self.cues:
+                cue = self.cues.popleft()
+                if cue['kin'] == "revoked":
+                    serder = cue["serder"]
+                    said = serder.ked["i"]
+                    creder = self.reger.creds.get(said)
+                    if creder is None:
+                        logger.error(f"revocation received for unknown credential {said}")
+
+                    prefixer = coring.Prefixer(qb64=creder.issuer)
+                    saider = coring.Saider(qb64=said)
+                    now = coring.Dater()
+
+                    self.cdb.snd.pin(keys=(saider.qb64,), val=prefixer)
+                    self.cdb.rev.pin(keys=(saider.qb64,), val=now)
+
+                yield self.tock
+
+            yield self.tock