mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/connectors/slack_api.py

@@ -0,0 +1,269 @@
+"""The Slack connector's tools, answered by Mobster with Slack's Web API and your sign-in (a user token), in place of
+Slack's MCP server, which takes only apps listed in the Slack Marketplace and a workspace's own internal apps."""
+
+import json
+import re
+import time
+from urllib.parse import urlencode
+
+from ..outlets import net, webhook
+from . import client as mcp
+from .api_session import ApiSession, Refusal, count_schema, required_text, short, tool_spec
+
+API = "https://slack.com/api"
+NAME = "Slack"
+SEARCH_LIMIT, HISTORY_LIMIT, THREAD_LIMIT = 20, 50, 100
+CHANNEL_PAGES = 5                   # users.conversations pages of 200
+TEXT_CHARS = 2000                   # what is kept of one message's text
+READ_LIMIT = 4 * 1024 * 1024       # a page of history with its blocks can pass net.READ_LIMIT
+CHANNEL_ID = re.compile(r"[CGD][A-Z0-9]{2,30}")
+CHANNEL_NAME = re.compile(r"#?([a-z0-9][a-z0-9._-]{0,79})")
+TS = re.compile(r"\d{9,11}\.\d{1,6}")
+SIGNED_OUT = frozenset({"invalid_auth", "token_expired", "not_authed", "token_revoked", "account_inactive",
+                        "user_removed_from_team", "team_disabled"})
+REFUSED = {
+    "channel_not_found": "Slack has no channel with that id, or you aren't in it. Use list_channels for the ids",
+    "not_in_channel": "You aren't in that channel. Join it in Slack first",
+    "is_archived": "That channel was archived",
+    "thread_not_found": "Slack has no thread at that ts in that channel. Use the ts of the thread's first message",
+    "restricted_action": "A workspace admin turned posting there off",
+    "cant_post": "You can't post in that channel",
+    "msg_too_long": "The message is too long for Slack. Shorten it",
+    "no_text": "The message has no text",
+    "feature_not_enabled": "Slack's search API isn't available on this workspace. Read a channel instead",
+    "assistant_search_context_disabled": "Slack's search is having trouble. Try again in a minute",
+    "query_too_long": "The search words are too long. Use fewer",
+}
+
+
+CHANNEL = {"type": "string", "description": "A channel's or DM's id (C…, G… or D…), or a channel's name with #."}
+TOOLS = (
+    tool_spec("search_messages", "Search Slack messages",
+              "Search your Slack messages in public and private channels, group DMs and DMs, newest first. Slack's "
+              "search words work: from:@name, in:#channel, before:2026-10-01, after:2026-10-01, is:thread. Each "
+              "message has its author, channel, channel id, ts and link.",
+              {"query": {"type": "string", "description": "What to search for, with Slack's search words."},
+               "limit": count_schema(SEARCH_LIMIT, 10),
+               "sort": {"type": "string", "enum": ["timestamp", "score"],
+                        "description": "timestamp: newest first (the default); score: best match first."}},
+              required=("query",)),
+    tool_spec("list_channels", "List my Slack channels",
+              "The public and private channels you're in: each one's id and #name.", {}),
+    tool_spec("read_channel", "Read a Slack channel",
+              "A channel's or DM's latest messages, newest first: each one's author's user id, ts, text and how many "
+              "replies its thread has.",
+              {"channel": CHANNEL,
+               "limit": count_schema(HISTORY_LIMIT, 20)},
+              required=("channel",)),
+    tool_spec("read_thread", "Read a Slack thread",
+              "A thread's messages, oldest first, from the ts of its first message (a search "
+              "result's or read_channel's).",
+              {"channel": CHANNEL, "ts": {"type": "string", "description": "The ts of the thread's first message."},
+               "limit": count_schema(THREAD_LIMIT, 50)},
+              required=("channel", "ts")),
+    tool_spec("send_message", "Send a Slack message",
+              "Post a message as you in a channel or DM, or as a reply in a thread. Plain text: Mobster escapes &, < "
+              "and >, so it can't mention @channel or people, or make links.",
+              {"channel": CHANNEL, "text": {"type": "string", "description": "The message."},
+               "thread_ts": {"type": "string", "description": "Reply in this thread: the ts of its first message."}},
+              required=("channel", "text"), read_only=False),
+)
+
+
+def connect(*, token=None, timeout=mcp.CONNECT_TIMEOUT, name=NAME, call=None):
+    """A ready SlackSession for ``token``. AuthNeeded without one, or when Slack refuses it."""
+    session = SlackSession(token, name=name, call=call)
+    session.initialize(timeout=timeout)
+    return session
+
+
+class SlackSession(ApiSession):
+    """The MCP session's surface (client.Session) over Slack's Web API."""
+
+    NAME, TOOLS = NAME, TOOLS
+
+    def _api(self, method, params, deadline, write=False):
+        """Slack's answer to ``method`` when it's ``ok``, or a ``Refusal``. Raises AuthNeeded, NotSent and, for a
+        write, OutcomeUnknown (a 5xx or no answer: it may have posted, and it's never sent again)."""
+        if not self.token:
+            raise mcp.AuthNeeded(f"{self.name} isn't signed in.")
+        timeout = max(1.0, deadline - time.monotonic())
+        body = urlencode({k: v for k, v in params.items() if v is not None}).encode()
+        headers = {"Authorization": f"Bearer {self.token}", "Content-Type": "application/x-www-form-urlencoded",
+                   "User-Agent": webhook.USER_AGENT}
+        try:
+            reply = self.call("POST", f"{API}/{method}", body, headers, timeout=timeout, read_limit=READ_LIMIT)
+        except net.NetError as error:
+            if error.unsent:
+                raise mcp.NotSent(error.message) from None
+            if write:
+                raise mcp.OutcomeUnknown(f"{error.message} The message may have posted: check Slack before you send it "
+                                         "again.") from None
+            raise mcp.OutcomeUnknown(error.message) from None
+        if reply.status == 429:
+            wait = reply.retry_after if str(reply.retry_after or "").isdigit() else "a few"
+            return Refusal(f"Slack asked Mobster to wait {wait} seconds. Try again then.")
+        if reply.status >= 500:
+            if write:
+                raise mcp.OutcomeUnknown(f"Slack answered {reply.status}. The message may have posted: check Slack "
+                                         "before you send it again.")
+            return Refusal(f"Slack answered {reply.status}. Try again in a minute.")
+        try:
+            answer = json.loads(reply.body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            answer = None
+        if not isinstance(answer, dict):
+            if write and reply.status == 200:
+                raise mcp.OutcomeUnknown("Slack's answer couldn't be read. The message may have posted: check Slack "
+                                         "before you send it again.")
+            return Refusal(f"Slack answered {reply.status} without a reply Mobster could read.")
+        if answer.get("ok") is True:
+            return answer
+        error = str(answer.get("error") or "unknown")[:60]
+        if error in SIGNED_OUT:
+            raise mcp.AuthNeeded(f"Slack signed Mobster out ({error}). Sign in to Slack again in Settings › "
+                                 "Connectors.")
+        if error == "missing_scope":
+            needed = str(answer.get("needed") or "a scope it wasn't given")[:120]
+            return Refusal(f"Your Slack sign-in can't do this: it needs {needed}. Sign in to Slack again in Settings › "
+                           "Connectors, and allow what Slack asks.")
+        if error in ("ratelimited", "rate_limited"):
+            return Refusal("Slack asked Mobster to wait. Try again in a minute.")
+        return Refusal(f"Slack refused ({error}). {REFUSED[error]}." if error in REFUSED
+                       else f"Slack refused ({error}).")
+
+    def initialize(self, timeout=mcp.CONNECT_TIMEOUT):
+        """auth.test: the token works (it needs no scope). AuthNeeded or NotSent when it doesn't."""
+        answer = self._api("auth.test", {}, time.monotonic() + timeout)
+        if isinstance(answer, Refusal):
+            raise mcp.NotSent(answer.message)
+        self.server_info = {"name": NAME, "team": str(answer.get("team") or "")[:100]}
+        self.ready = True
+        return {"serverInfo": self.server_info}
+
+    def ping(self, timeout=mcp.PING_TIMEOUT):
+        if not self.ready:
+            raise mcp.NotSent(f"{self.name} isn't connected.")
+        answer = self._api("auth.test", {}, time.monotonic() + timeout)
+        if isinstance(answer, Refusal):
+            raise mcp.NotSent(answer.message)
+        return True
+
+    def _search_messages(self, args, deadline):
+        query = required_text(args.get("query"), "query", 500)
+        answer = self._api("assistant.search.context", {
+            "query": query, "channel_types": "public_channel,private_channel,mpim,im", "content_types": "messages",
+            "limit": _limit(args.get("limit"), 10, SEARCH_LIMIT),
+            "sort": _choice(args.get("sort"), ("timestamp", "score")),
+            "sort_dir": "desc"}, deadline)
+        if isinstance(answer, Refusal):
+            return answer
+        results = answer.get("results") if isinstance(answer.get("results"), dict) else {}
+        messages = [{"author": short(m.get("author_name") or m.get("author_user_id"), 100),
+                     "channel": short(m.get("channel_name"), 100), "channelId": short(m.get("channel_id"), 40),
+                     "ts": short(m.get("message_ts"), 40), "text": short(m.get("content"), TEXT_CHARS),
+                     "link": short(m.get("permalink"), 300)}
+                    for m in results.get("messages") or () if isinstance(m, dict)]
+        more = bool((answer.get("response_metadata") or {}).get("next_cursor"))
+        return {"messages": messages, "more": more}
+
+    def _channels(self, deadline):
+        found, cursor = [], None
+        for _ in range(CHANNEL_PAGES):
+            answer = self._api("users.conversations", {"types": "public_channel,private_channel",
+                                                       "exclude_archived": "true", "limit": "200", "cursor": cursor},
+                               deadline)
+            if isinstance(answer, Refusal):
+                return answer
+            for item in answer.get("channels") or ():
+                if isinstance(item, dict) and CHANNEL_ID.fullmatch(str(item.get("id"))) \
+                        and isinstance(item.get("name"), str):
+                    found.append({"id": item["id"], "name": "#" + item["name"][:80],
+                                  "private": bool(item.get("is_private"))})
+            cursor = (answer.get("response_metadata") or {}).get("next_cursor")
+            if not cursor:
+                break
+        return sorted(found, key=lambda item: item["name"])
+
+    def _list_channels(self, args, deadline):
+        found = self._channels(deadline)
+        return found if isinstance(found, Refusal) else {"channels": found}
+
+    def _channel_id(self, value, deadline):
+        """A channel id as given, or the id of the channel you're in by that #name."""
+        text = required_text(value, "channel", 90)
+        if CHANNEL_ID.fullmatch(text):
+            return text
+        named = CHANNEL_NAME.fullmatch(text.lower())
+        if not named:
+            raise ValueError("channel is a channel's id (C…, G… or D…) or its #name")
+        found = self._channels(deadline)
+        if isinstance(found, Refusal):
+            return found
+        match = next((c["id"] for c in found if c["name"] == "#" + named.group(1)), None)
+        if match is None:
+            raise ValueError(f"You aren't in a channel called #{named.group(1)}. Use list_channels for the ones "
+                             "you're in")
+        return match
+
+    def _read_channel(self, args, deadline):
+        channel = self._channel_id(args.get("channel"), deadline)
+        if isinstance(channel, Refusal):
+            return channel
+        answer = self._api("conversations.history", {"channel": channel,
+                                                     "limit": _limit(args.get("limit"), 20, HISTORY_LIMIT)}, deadline)
+        return answer if isinstance(answer, Refusal) else {"channelId": channel, "messages": _messages(answer),
+                                                           "more": bool(answer.get("has_more"))}
+
+    def _read_thread(self, args, deadline):
+        channel = self._channel_id(args.get("channel"), deadline)
+        if isinstance(channel, Refusal):
+            return channel
+        ts = required_text(args.get("ts"), "ts", 20)
+        if not TS.fullmatch(ts):
+            raise ValueError("ts is a message's ts, such as 1760000000.123456")
+        answer = self._api("conversations.replies", {"channel": channel, "ts": ts,
+                                                     "limit": _limit(args.get("limit"), 50, THREAD_LIMIT)}, deadline)
+        return answer if isinstance(answer, Refusal) else {"channelId": channel, "messages": _messages(answer),
+                                                           "more": bool(answer.get("has_more"))}
+
+    def _send_message(self, args, deadline):
+        channel = self._channel_id(args.get("channel"), deadline)
+        if isinstance(channel, Refusal):
+            return channel
+        text = required_text(args.get("text"), "text", 40_000)
+        thread = args.get("thread_ts")
+        if thread is not None and not TS.fullmatch(str(thread)):
+            raise ValueError("thread_ts is the ts of the thread's first message, such as 1760000000.123456")
+        # &, < and > are escaped and link_names is off, so text from a screen can't mention @channel or a person, or
+        # make a link.
+        answer = self._api("chat.postMessage", {"channel": channel, "text": webhook.slack_text(text),
+                                                "thread_ts": thread,
+                                                "link_names": "false", "unfurl_links": "false",
+                                                "unfurl_media": "false"}, deadline, write=True)
+        if isinstance(answer, Refusal):
+            return answer
+        return {"posted": True, "channelId": short(answer.get("channel"), 40), "ts": short(answer.get("ts"), 40)}
+
+
+def _messages(answer):
+    return [{"user": short(m.get("user") or m.get("bot_id"), 40), "ts": short(m.get("ts"), 40),
+             "text": short(m.get("text"), TEXT_CHARS),
+             "replies": m.get("reply_count") if isinstance(m.get("reply_count"), int) else 0}
+            for m in answer.get("messages") or () if isinstance(m, dict)]
+
+
+def _limit(value, default, top):
+    if value is None:
+        return str(default)
+    if type(value) is not int or not 1 <= value <= top:
+        raise ValueError(f"limit is a whole number from 1 to {top}")
+    return str(value)
+
+
+def _choice(value, choices):
+    if value is None:
+        return choices[0]
+    if value not in choices:
+        raise ValueError(f"sort is {' or '.join(choices)}")
+    return value

mobile_agent/connectors/steps.py

@@ -0,0 +1,92 @@
+"""The workflow builder's "Use a connector" step (batch.register_step, kind ``connector``): one tool of a connected
+service, called by the workflow itself, with no model and without the phone."""
+
+import json
+
+from . import client as mcp
+from . import service as connector_service
+from . import store as connector_store
+
+ARGS_CHARS = 16_000
+
+
+def _service(runtime):
+    service = connector_service.service_for(runtime)
+    if service is None:
+        raise ValueError("Connectors aren't available in this Mobster")
+    return service
+
+
+def validate(step, runtime):
+    """The step as saved, or ValueError with a sentence."""
+    if set(step) - {"id", "kind", "connector", "tool", "arguments"}:
+        raise ValueError("A connector step has a connector, a tool and its arguments")
+    connector, tool = step.get("connector"), step.get("tool")
+    if not isinstance(connector, str) or not connector:
+        raise ValueError("Choose a connector")
+    if not isinstance(tool, str) or not 0 < len(tool) <= 128:
+        raise ValueError("Choose one of the connector's tools")
+    arguments = step.get("arguments") if step.get("arguments") is not None else {}
+    if not isinstance(arguments, dict):
+        raise ValueError("A connector step's arguments are one JSON object")
+    if len(json.dumps(arguments)) > ARGS_CHARS:
+        raise ValueError("Those arguments are too long")
+    if runtime is not None:
+        row = _service(runtime).store.get(connector)
+        if row is None:
+            raise ValueError("That connector was removed. Choose another one.")
+        if row["tools"] and not any(t["name"] == tool for t in row["tools"]):
+            raise ValueError(f"{row['name']} has no tool called {tool}. Test it in Settings › "
+                             "Connectors, then choose again.")
+    return {"connector": connector, "tool": tool, "arguments": arguments}
+
+
+def _fill(value, values, fill):
+    if isinstance(value, str):
+        return fill(value, values)
+    if isinstance(value, list):
+        return [_fill(item, values, fill) for item in value]
+    if isinstance(value, dict):
+        return {key: _fill(item, values, fill) for key, item in value.items()}
+    return value
+
+
+def run(batch, step, values):
+    """One call. {"answer", "line"}, or batch.Stop with a sentence (nothing sent unless the sentence says so)."""
+    from ..secret_filter import redact
+    from ..workflows.records import Stop
+    from .skill import result_text
+    service = connector_service.service_for(batch.runtime)
+    if service is None:
+        raise Stop("dispatch_failed", "Connectors aren't available in this Mobster.")
+    row = service.store.get(step["connector"])
+    if row is None:
+        raise Stop("dispatch_failed", "The connector this step uses was removed. Choose another one.")
+    tool, name = step["tool"], row["name"]
+    if not row["enabled"]:
+        raise Stop("dispatch_failed", f"{name} is turned off in Settings › Connectors, so this step didn't run.")
+    if row["tools"] and not any(t["name"] == tool for t in row["tools"]):
+        raise Stop("dispatch_failed", f"{name} no longer has a tool called {tool}.")
+    mode = connector_store.mode_of(row, tool)
+    if mode == "off":
+        raise Stop("dispatch_failed", f"{name}: {tool} is blocked in Settings › Connectors, so this step didn't run.")
+    if mode != "read":
+        raise Stop("dispatch_failed", f"{name}: {tool} asks you first, and a workflow step has nobody to ask, so "
+                   "nothing was sent. Allow it in Settings › Connectors, or use "
+                   "a task step that names it.")
+    arguments = _fill(step.get("arguments") or {}, values, batch._fill)
+    try:
+        result = service.call(row, tool, arguments)
+    except mcp.OutcomeUnknown as error:
+        raise Stop("dispatch_failed", f"{name}: {tool} didn't answer ({error.message}) It may or may not have "
+                   f"happened, so the workflow stopped and won't send it again.",
+                   unknown=True) from None
+    except mcp.ConnectorError as error:
+        raise Stop("dispatch_failed", f"{name}: {tool} wasn't called: {redact(error.message)}",
+                   retryable=error.sent is False) from None
+    text = result_text(result)
+    if result.get("isError"):
+        raise Stop("dispatch_failed", f"{name}: {tool} returned an error: {text[:200]}")
+    structured = result.get("structuredContent")
+    return {"answer": text, "line": f"Used {name}: {tool}",
+            "structured": structured if isinstance(structured, dict) else None}

mobile_agent/connectors/store.py

@@ -0,0 +1,144 @@
+"""Connectors' state in the run journal: schema ``connectors`` v1, in the same private SQLite file (0600).
+
+``connectors``: one row per MCP server the person added.
+
+| Column | What it holds |
+|---|---|
+| id | 12 hex characters |
+| name | what the person and the model call it ("Notion"); unique, case ignored |
+| transport | "stdio" or "http" |
+| command, args | stdio: the command and its arguments (JSON list). Never an env value |
+| url | http: the server's URL |
+| auth | "none", "token" or "oauth": what the Keychain item holds (vault.py) |
+| enabled | 0 or 1 |
+| preset | the preset's key ("notion"), or NULL |
+| plugin | the plugin that added it, or NULL (plugins track) |
+| tools | the last ``tools/list``, trimmed (JSON list of {name, description, inputSchema, readOnly}) |
+| tools_at | when ``tools`` was read |
+| modes | {tool: "read" \\| "ask" \\| "off"} the person chose (JSON). A tool not in it is "ask" |
+| last_test | {ok, at, message} of the last connect (JSON) |
+| created_at, updated_at | seconds |
+
+Writes go through ``Journal.transaction()``, reads hold ``Journal.lock``.
+"""
+
+import json
+import sqlite3
+
+from ..journal import JournalError
+from . import presets
+
+SCHEMA = "connectors"
+VERSION = 1
+MAX_CONNECTORS = 50
+MODES = ("read", "ask", "off")
+DEFAULT_MODE = "ask"          # unknown means ask: a tool nobody chose for never runs unasked
+COLUMNS = ("id", "name", "transport", "command", "args", "url", "auth", "enabled", "preset", "plugin", "tools",
+           "tools_at", "modes", "last_test", "created_at", "updated_at")
+JSON_COLUMNS = ("args", "tools", "modes", "last_test")
+
+
+def migrate(connection, from_version):
+    if from_version < 1:
+        connection.execute("""CREATE TABLE IF NOT EXISTS connectors (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            transport TEXT NOT NULL CHECK (transport IN ('stdio', 'http')),
+            command TEXT,
+            args TEXT,
+            url TEXT,
+            auth TEXT NOT NULL DEFAULT 'none',
+            enabled INTEGER NOT NULL DEFAULT 1,
+            preset TEXT,
+            plugin TEXT,
+            tools TEXT,
+            tools_at REAL,
+            modes TEXT,
+            last_test TEXT,
+            created_at REAL NOT NULL,
+            updated_at REAL NOT NULL)""")
+
+
+def mode_of(row, tool):
+    """The mode of ``tool`` on a connector row: what the person chose, else "ask"."""
+    mode = (row.get("modes") or {}).get(tool)
+    mode = mode if mode in MODES else DEFAULT_MODE
+    # A tool of its preset's always_ask (a send to other people) never runs unasked: "read" counts as "ask".
+    if mode == "read" and tool in (presets.preset(row.get("preset")) or {}).get("always_ask", ()):
+        return "ask"
+    return mode
+
+
+def _row(values):
+    if values is None:
+        return None
+    row = dict(zip(COLUMNS, values))
+    for column in JSON_COLUMNS:
+        try:
+            row[column] = json.loads(row[column]) if row[column] else None
+        except ValueError:
+            row[column] = None
+    row["args"] = row["args"] or []
+    row["tools"] = row["tools"] or []
+    row["modes"] = row["modes"] if isinstance(row["modes"], dict) else {}
+    row["enabled"] = bool(row["enabled"])
+    return row
+
+
+class ConnectorStore:
+    def __init__(self, journal):
+        self.journal = journal
+
+    def _read(self, sql, args=()):
+        with self.journal.lock:
+            if self.journal.connection is None:
+                raise JournalError("The run journal is closed")
+            try:
+                return self.journal.connection.execute(sql, args).fetchall()
+            except sqlite3.Error:
+                raise JournalError("Mobster could not read its connectors") from None
+
+    def all(self):
+        return [_row(r) for r in self._read(f"SELECT {', '.join(COLUMNS)} FROM connectors ORDER BY created_at, rowid")]
+
+    def get(self, connector_id):
+        rows = self._read(f"SELECT {', '.join(COLUMNS)} FROM connectors WHERE id=?", (connector_id,))
+        return _row(rows[0]) if rows else None
+
+    def count(self):
+        return self._read("SELECT count(*) FROM connectors")[0][0]
+
+    def add(self, row):
+        values = []
+        for column in COLUMNS:
+            value = row.get(column)
+            if column in JSON_COLUMNS:
+                value = json.dumps(value) if value is not None else None
+            elif column == "enabled":
+                value = int(bool(value if value is not None else True))
+            values.append(value)
+        with self.journal.transaction() as connection:
+            connection.execute(f"INSERT INTO connectors({', '.join(COLUMNS)}) VALUES ({', '.join('?' * len(COLUMNS))})",
+                               values)
+        return self.get(row["id"])
+
+    def update(self, connector_id, **changes):
+        allowed = set(COLUMNS) - {"id", "created_at"}
+        if set(changes) - allowed:
+            raise ValueError("Unknown connector field")
+        values = []
+        for key, value in changes.items():
+            if key in JSON_COLUMNS:
+                value = json.dumps(value) if value is not None else None
+            elif key == "enabled":
+                value = int(bool(value))
+            values.append(value)
+        if values:
+            with self.journal.transaction() as connection:
+                connection.execute(f"UPDATE connectors SET {', '.join(f'{k}=?' for k in changes)} WHERE id=?",
+                                   [*values, connector_id])
+        return self.get(connector_id)
+
+    def delete(self, connector_id):
+        with self.journal.transaction() as connection:
+            connection.execute("DELETE FROM connectors WHERE id=?", (connector_id,))

mobile_agent/connectors/vault.py

@@ -0,0 +1,72 @@
+"""Where a connector's secrets live: one generic password per connector in the login Keychain, readable only
+by Mobster's own programs (keychain_acl.py), as outlets/vault.py keeps a destination's address."""
+
+import base64
+import json
+import re
+
+from . import keystore
+
+SERVICE = "app.mobster.desktop.connectors"
+ENV = "MOBSTER_CONNECTORS_KEYCHAIN"
+ACCOUNT = re.compile(r"connector:[0-9a-f]{12}")
+WORD = re.compile(r"[A-Za-z0-9_-]{1,16000}")
+VaultError = keystore.VaultError
+
+
+def account_for(connector_id):
+    account = f"connector:{connector_id}"
+    if not ACCOUNT.fullmatch(account):
+        raise ValueError("A connector's id is 12 hex characters")
+    return account
+
+
+def encode(value):
+    raw = json.dumps(value, separators=(",", ":")).encode()
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def decode(word):
+    try:
+        value = json.loads(base64.urlsafe_b64decode(word + "=" * (-len(word) % 4)))
+    except (ValueError, TypeError):
+        raise VaultError("Mobster couldn't read a connector's sign-in") from None
+    if not isinstance(value, dict):
+        raise VaultError("Mobster couldn't read a connector's sign-in")
+    return value
+
+
+class Vault:
+    """``put(id, secrets)``, ``get(id) -> dict`` ({} when none) and ``delete(id)`` over a raw store."""
+
+    def put(self, connector_id, secrets):
+        secrets = {k: v for k, v in (secrets or {}).items() if v}
+        if not secrets:
+            self.delete(connector_id)
+            return
+        self._set(account_for(connector_id), encode(secrets))
+
+    def get(self, connector_id):
+        word = self._get(account_for(connector_id))
+        return decode(word) if word else {}
+
+    def update(self, connector_id, **changes):
+        current = self.get(connector_id)
+        current.update(changes)
+        self.put(connector_id, current)
+        return current
+
+    def delete(self, connector_id):
+        self._delete(account_for(connector_id))
+
+
+class FileVault(keystore.FileStore, Vault):
+    files = "connectors"
+
+
+class KeychainVault(keystore.KeychainStore, Vault):
+    service, noun, word = SERVICE, "sign-in", WORD
+
+
+def backend():
+    return keystore.backend(ENV, FileVault, KeychainVault)