touchque-authenticator 4.2.0__py3-none-any.whl

touchque/resources/action_types.py

@@ -0,0 +1,52 @@
+from typing import Any, Dict, List, Optional
+
+from ..http_client import HttpClient
+
+# The Second Thought questions an action type can ask (at most two).
+SECOND_THOUGHT_QUESTIONS = (
+    'someone_guiding',
+    'safe_account',
+    'remote_access',
+    'asked_for_code',
+    'support_call',
+    'met_online',
+    'promised_return',
+    'know_recipient',
+    'sim_in_hand',
+)
+
+_KEEP: Any = object()
+
+
+class ActionTypes:
+    """Action types ("LOGIN", "SEND_MONEY", …) — what a user is asked to
+    approve. Define them from code at start-up instead of clicking them
+    into the Dashboard. (Before 4.0 this was ``tq.actions``; ``tq.actions``
+    is TouchQue Actions now.)"""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def define(self, type: str, name: Optional[str] = None, description: Optional[str] = None,
+               critical: Optional[bool] = None, second_thought: Optional[Dict[str, Any]] = _KEEP) -> Dict[str, Any]:
+        """Creates the action type, or updates its name, description,
+        critical flag and Second Thought questions. Safe to call on every
+        start-up: it never re-enables a type an admin disabled.
+
+        ``second_thought``: ``{'questions': [...], 'locale': 'tr'|'en'}``, at
+        most two of ``SECOND_THOUGHT_QUESTIONS``, asked on the phone before
+        Approve. A risky answer never refuses: the approval comes back
+        ``provisional`` and the phone asks "Was this you?" later. ``None``
+        turns them off; leave it out to keep what the Dashboard has.
+        """
+        body: Dict[str, Any] = {'type': type, 'name': name or type}
+        if description is not None:
+            body['description'] = description
+        if critical is not None:
+            body['critical'] = critical
+        if second_thought is not _KEEP:
+            body['secondThought'] = second_thought
+        return self._http.post('/action-types', body)
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._http.get('/action-types')

touchque/resources/actions.py

@@ -0,0 +1,234 @@
+"""TouchQue Actions: your own code at points of the approval pipeline (before
+the push is sent, the silent sign-in decision, after an approval, fraud
+reports, device and recovery events). TouchQue runs it in a sandbox; this
+resource deploys, tests, replays and observes it::
+
+    tq.actions.deploy(
+        'night-alert',
+        trigger='approval.decided',
+        template={'id': 'alert', 'params': {'channel': 'slack', 'when': {'countries': ['TR'], 'hours': {'from': 0, 'to': 6}}}},
+    )
+
+Action code itself is JavaScript (``exports.onExecute = async (event, api) => {...}``),
+whatever language your server is written in.
+"""
+import re
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+_SLUG_RE = re.compile(r'^[a-z0-9][a-z0-9-]{1,62}$')
+_SECRET_RE = re.compile(r'^[A-Z][A-Z0-9_]{0,63}$')
+_TEMPLATE_RE = re.compile(r'^[a-z_]{1,64}$')
+
+
+def _slug_path(slug: str) -> str:
+    if not isinstance(slug, str) or not _SLUG_RE.match(slug):
+        raise TouchQueConfigException('An Action slug is 2-63 lowercase letters, digits or - (e.g. "night-alert")')
+    return f'/actions/{slug}'
+
+
+def _secret_path(name: str) -> str:
+    if not isinstance(name, str) or not _SECRET_RE.match(name):
+        raise TouchQueConfigException('A secret name is capital letters, digits or _ (e.g. SLACK_WEBHOOK_URL)')
+    return f'/actions/secrets/{name}'
+
+
+def _draft(trigger=None, code=None, template=None, slug=None, secrets=None, allowed_hosts=None,
+           capabilities=None) -> Dict[str, Any]:
+    body: Dict[str, Any] = {}
+    if trigger is not None:
+        body['trigger'] = trigger
+    if slug is not None:
+        body['slug'] = slug
+    if code is not None:
+        body['code'] = code
+    if template is not None:
+        body['template'] = template
+    if secrets is not None:
+        body['secrets'] = list(secrets)
+    if allowed_hosts is not None:
+        body['allowedHosts'] = list(allowed_hosts)
+    if capabilities is not None:
+        body['capabilities'] = list(capabilities)
+    return body
+
+
+def _iso(value: Union[str, datetime, None]) -> Optional[str]:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
+class ActionSecrets:
+    """Secrets your Actions read (``event.secrets.NAME``) or notify with. A
+    value is encrypted and never readable again through the API."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def set(self, name: str, value: str) -> Dict[str, Any]:
+        if not isinstance(value, str) or not value:
+            raise TouchQueConfigException('A secret value is a non-empty string')
+        return self._http.put(_secret_path(name), {'value': value})
+
+    def list(self) -> List[Dict[str, Any]]:
+        """Names only."""
+        res = self._http.get('/actions/secrets')
+        return res.get('secrets', []) if isinstance(res, dict) else []
+
+    def delete(self, name: str) -> Dict[str, Any]:
+        return self._http.delete(_secret_path(name))
+
+
+class Actions:
+    """TouchQue Actions management: deploy, roll back, test, dry run, logs,
+    metrics, secrets and no-code templates."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+        self.secrets = ActionSecrets(http)
+
+    def deploy(self, slug: str, trigger: Optional[str] = None, code: Optional[str] = None,
+               template: Optional[Dict[str, Any]] = None, name: Optional[str] = None,
+               secrets: Optional[List[str]] = None, allowed_hosts: Optional[List[str]] = None,
+               capabilities: Optional[List[str]] = None, on_failure: Optional[str] = None,
+               order: Optional[int] = None, enabled: Optional[bool] = None,
+               activate: Optional[bool] = None) -> Dict[str, Any]:
+        """Creates the Action or adds a version and makes it live (idempotent:
+        the same code and settings change nothing). A version asking for a
+        loosening capability (``skip_number_match``, ``override_block``,
+        ``allow_silent``) waits for an admin's phone approval: the answer then
+        has ``deployed: False`` and ``approval['required']``.
+
+        :param trigger: required for a new Action (``login.request``,
+            ``risk.check``, ``agent.approval``, ``approval.decided``, …); cannot change later.
+        :param code: JavaScript exporting ``onExecute``.
+        :param template: ``{'id': 'alert' | 'block_or_step_up' | ..., 'params': {...}}``
+            instead of code.
+        :param on_failure: pre triggers only: ``continue`` (default, never
+            blocks), ``step_up`` or ``deny`` when the Action errors or times out.
+        :param activate: ``False`` saves the version without making it live.
+        """
+        if code is None and template is None:
+            raise TouchQueConfigException('deploy() needs code or template')
+        body = _draft(trigger=trigger, code=code, template=template, secrets=secrets,
+                      allowed_hosts=allowed_hosts, capabilities=capabilities)
+        if name is not None:
+            body['name'] = name
+        if on_failure is not None:
+            body['onFailure'] = on_failure
+        if order is not None:
+            body['order'] = order
+        if enabled is not None:
+            body['enabled'] = enabled
+        if activate is not None:
+            body['activate'] = activate
+        return self._http.put(_slug_path(slug), body)
+
+    def list(self) -> List[Dict[str, Any]]:
+        res = self._http.get('/actions')
+        return res.get('actions', []) if isinstance(res, dict) else []
+
+    def get(self, slug: str) -> Dict[str, Any]:
+        """The Action, the active version's code and its versions."""
+        return self._http.get(_slug_path(slug))
+
+    def version(self, slug: str, number: int) -> Dict[str, Any]:
+        """One version, with its code."""
+        if not isinstance(number, int):
+            raise TouchQueConfigException('version() needs a version number')
+        return self._http.get(f'{_slug_path(slug)}/versions/{number}')
+
+    def update(self, slug: str, name: Optional[str] = None, enabled: Optional[bool] = None,
+               order: Optional[int] = None, on_failure: Optional[str] = None) -> Dict[str, Any]:
+        """Rename, turn on or off, reorder, change on_failure."""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body['name'] = name
+        if enabled is not None:
+            body['enabled'] = enabled
+        if order is not None:
+            body['order'] = order
+        if on_failure is not None:
+            body['onFailure'] = on_failure
+        return self._http.patch(_slug_path(slug), body).get('action')
+
+    def delete(self, slug: str) -> Dict[str, Any]:
+        return self._http.delete(_slug_path(slug))
+
+    def rollback(self, slug: str, version: Optional[int] = None) -> Dict[str, Any]:
+        """Back to ``version``, or to the newest runnable version before the
+        active one. Takes effect at once."""
+        return self._http.post(f'{_slug_path(slug)}/rollback', {} if version is None else {'version': version})
+
+    def test(self, trigger: Optional[str] = None, code: Optional[str] = None,
+             template: Optional[Dict[str, Any]] = None, slug: Optional[str] = None,
+             event_id: Optional[str] = None, event: Optional[Dict[str, Any]] = None,
+             secrets: Optional[List[str]] = None, allowed_hosts: Optional[List[str]] = None,
+             capabilities: Optional[List[str]] = None, network: Optional[bool] = None) -> Dict[str, Any]:
+        """Runs a draft (or the deployed Action ``slug``) once on a recorded
+        event (``event_id``), your own ``event`` or the trigger's sample.
+        Sends no notification."""
+        body = _draft(trigger=trigger, code=code, template=template, slug=slug, secrets=secrets,
+                      allowed_hosts=allowed_hosts, capabilities=capabilities)
+        if event_id is not None:
+            body['eventId'] = event_id
+        if event is not None:
+            body['event'] = event
+        if network is not None:
+            body['network'] = network
+        return self._http.post('/actions/test', body)
+
+    def dry_run(self, trigger: Optional[str] = None, code: Optional[str] = None,
+                template: Optional[Dict[str, Any]] = None, slug: Optional[str] = None,
+                replaces: Optional[str] = None, limit: Optional[int] = None,
+                since: Union[str, datetime, None] = None, on_failure: Optional[str] = None,
+                secrets: Optional[List[str]] = None, allowed_hosts: Optional[List[str]] = None,
+                capabilities: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Replays a draft against recent real decisions: how many it would
+        have changed (``changed``, ``transitions`` such as
+        ``{'push→number_match': 12}``), notifications it would have sent,
+        errors and timing. ``replaces``: the deployed Action it would replace."""
+        body = _draft(trigger=trigger, code=code, template=template, slug=slug, secrets=secrets,
+                      allowed_hosts=allowed_hosts, capabilities=capabilities)
+        if replaces is not None:
+            body['replaces'] = replaces
+        if on_failure is not None:
+            body['onFailure'] = on_failure
+        if limit is not None:
+            body['limit'] = limit
+        if since is not None:
+            body['since'] = _iso(since)
+        return self._http.post('/actions/dry-run', body)
+
+    def events(self, trigger: Optional[str] = None, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """Recorded events (newest first, kept 30 days); use an id with test()."""
+        res = self._http.get('/actions/events', {'trigger': trigger, 'limit': limit})
+        return res.get('events', []) if isinstance(res, dict) else []
+
+    def logs(self, slug: str, limit: Optional[int] = None,
+             before: Union[str, datetime, None] = None) -> List[Dict[str, Any]]:
+        """Live runs: decision, notifications, console output, errors."""
+        res = self._http.get(f'{_slug_path(slug)}/logs', {'limit': limit, 'before': _iso(before)})
+        return res.get('logs', []) if isinstance(res, dict) else []
+
+    def metrics(self, slug: str, window: Optional[str] = None) -> Dict[str, Any]:
+        """``window``: ``1h``, ``24h`` (default), ``7d`` or ``30d``."""
+        return self._http.get(f'{_slug_path(slug)}/metrics', {'window': window})
+
+    def triggers(self) -> Dict[str, Any]:
+        """Every trigger with its decisions, capabilities, notification types and a sample event."""
+        return self._http.get('/actions/triggers')
+
+    def templates(self) -> List[Dict[str, Any]]:
+        res = self._http.get('/actions/templates')
+        return res.get('templates', []) if isinstance(res, dict) else []
+
+    def render_template(self, id: str, trigger: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """A template as plain code (to read, or to start a code Action from)."""
+        if not isinstance(id, str) or not _TEMPLATE_RE.match(id):
+            raise TouchQueConfigException('Unknown template id')
+        return self._http.post(f'/actions/templates/{id}/render', {'trigger': trigger, 'params': params or {}})

touchque/resources/agents.py

@@ -0,0 +1,236 @@
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import time
+
+from ..approval_token import assert_approval_matches, decode_approval_token, verify_approval_token_with
+from ..exceptions import TouchQueApprovalMismatchError, TouchQueConfigException
+from ..http_client import HttpClient
+
+
+def _public_only(jwk: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Refuses a private key before it leaves this process."""
+    if isinstance(jwk, dict) and 'd' in jwk:
+        raise TouchQueConfigException(
+            "Pass the agent's PUBLIC key: this one has private parts (d). "
+            'The private key must stay where the agent runs.')
+    return jwk
+
+
+def _id(value: str) -> str:
+    return quote(value, safe='')
+
+
+class AgentVault:
+    """The token vault for your agents (``client.agents.vault``): after your own OAuth flow with a
+    person, deposit their tokens; TouchQue keeps them sealed and refreshes them, and the agents a
+    connection names get a short-lived access token (``TouchQueAgent.get_connection_token``),
+    never the refresh token."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def list_connections(self) -> List[Dict[str, Any]]:
+        return self._http.get('/agents/vault/connections')['connections']
+
+    def put_connection(self, name: str, provider: str, client_id: str, client_secret: Optional[str] = None,
+                       tenant: Optional[str] = None, issuer: Optional[str] = None, agent_ids: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Adds or replaces a connection (google, microsoft, github, facebook, linkedin, x, oidc);
+        ``client_secret`` is kept when left out of a replacement."""
+        body: Dict[str, Any] = {'provider': provider, 'clientId': client_id}
+        for key, value in (('clientSecret', client_secret), ('tenant', tenant), ('issuer', issuer), ('agentIds', agent_ids)):
+            if value is not None:
+                body[key] = value
+        return self._http.put(f'/agents/vault/connections/{_id(name)}', body)['connection']
+
+    def remove_connection(self, name: str) -> Dict[str, Any]:
+        """Removes it, and every person's tokens kept for it."""
+        return self._http.delete(f'/agents/vault/connections/{_id(name)}')
+
+    def deposit(self, connection: str, user: str, access_token: str, refresh_token: Optional[str] = None,
+                expires_in: Optional[int] = None, scope: Optional[str] = None) -> Dict[str, Any]:
+        """Keeps a person's tokens (replacing earlier ones) after your own OAuth flow with them."""
+        body: Dict[str, Any] = {'accessToken': access_token}
+        for key, value in (('refreshToken', refresh_token), ('expiresIn', expires_in), ('scope', scope)):
+            if value is not None:
+                body[key] = value
+        return self._http.put(f'/agents/vault/accounts/{_id(connection)}/{_id(user)}', body)['account']
+
+    def list_accounts(self, user: str) -> List[Dict[str, Any]]:
+        """A person's accounts in the vault (never a token)."""
+        return self._http.get('/agents/vault/accounts', {'externalUsername': user})['accounts']
+
+    def remove_account(self, connection: str, user: str) -> None:
+        """Deletes a person's tokens: agents get nothing more for them there."""
+        self._http.delete(f'/agents/vault/accounts/{_id(connection)}/{_id(user)}')
+
+
+class Agents:
+    """AI agents as identities of their own (``client.agents``): register an
+    agent with its PUBLIC key, give it an accountable owner and the action
+    types it may ask approvals for, suspend, revoke or stop every agent at
+    once. The agent itself never gets your API key: it signs in with its own
+    key (``TouchQueAgent``).
+
+        keys = generate_agent_key()                       # where the agent runs
+        agent = client.agents.create('Invoice bot', ['PAY_INVOICE'], public_key=keys['public_jwk'])
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+        # The token vault: people's tokens at other services, for your agents.
+        self.vault = AgentVault(http)
+        self._jwks: Optional[Dict[str, Any]] = None
+        self._jwks_at = 0.0
+        self._audience: Optional[str] = None
+
+    def redeem_approval(self, token: str, user: Optional[str] = None, type: Optional[str] = None,
+                        authorization_details: Any = None) -> Dict[str, Any]:
+        """Uses an agent's approval exactly once, right before you execute:
+        checks your expectations against the token first (nothing is used on a
+        mismatch), then TouchQue checks the token and marks it used, and the
+        answer is checked again. Raises TouchQueApprovalMismatchError or a
+        TouchQueAPIException (``already_redeemed``, ``token_expired``...)."""
+        expect = {'user': user, 'type': type, 'authorization_details': authorization_details}
+        assert_approval_matches(decode_approval_token(token)['claims'], **expect)
+        approval = self._http.post('/agents/approvals/redeem', {'token': token})['approval']
+        assert_approval_matches({'sub': approval.get('externalUsername'), 'type': approval.get('type'),
+                                 'authorization_details': approval.get('authorizationDetails')}, **expect)
+        return approval
+
+    def approval_audience(self) -> str:
+        """The ``aud`` of this workspace's approval tokens (``touchque:workspace:<id>``),
+        from GET /agents/approval-audience; asked once, then kept."""
+        if not self._audience:
+            audience = (self._http.get('/agents/approval-audience') or {}).get('audience')
+            if not isinstance(audience, str) or not audience:
+                raise TouchQueApprovalMismatchError("Touchque did not name this workspace's approval audience")
+            self._audience = audience
+        return self._audience
+
+    def verify_approval_token(self, token: str, audience: Optional[str] = None, **expect: Any) -> Dict[str, Any]:
+        """Verifies an approval token offline (TouchQue's published keys, expiry,
+        ``aud``, ``user`` / ``type`` / ``authorization_details``). ``aud`` must be
+        this workspace's: ``audience`` defaults to ``approval_audience()``, and a
+        token without aud or for another workspace is refused. It does not make
+        the token single-use: ``redeem_approval`` does."""
+        audience = audience or self.approval_audience()
+        if self._jwks is None or time.time() - self._jwks_at > 300:
+            self._jwks, self._jwks_at = self._http.get('/agents/jwks.json'), time.time()
+        try:
+            return verify_approval_token_with(token, self._jwks, audience=audience, **expect)
+        except TouchQueApprovalMismatchError as exc:
+            if 'unknown key' not in str(exc):
+                raise
+            self._jwks, self._jwks_at = self._http.get('/agents/jwks.json'), time.time()
+            return verify_approval_token_with(token, self._jwks, audience=audience, **expect)
+
+    def create(self, name: str, allowed_types: List[str], public_key: Optional[Dict[str, Any]] = None,
+               public_keys: Optional[List[Dict[str, Any]]] = None, description: Optional[str] = None,
+               owner_email: Optional[str] = None, platform: Optional[str] = None,
+               review_in_days: Optional[int] = None) -> Dict[str, Any]:
+        """Registers an agent (needs the ``agents:write`` scope). ``owner_email``:
+        the accountable person, a member of the organization (default: the
+        API key's creator); the agent stops when they leave."""
+        body: Dict[str, Any] = {'name': name, 'allowedTypes': allowed_types}
+        if description is not None:
+            body['description'] = description
+        if owner_email is not None:
+            body['ownerEmail'] = owner_email
+        if platform is not None:
+            body['platform'] = platform
+        if review_in_days is not None:
+            body['reviewInDays'] = review_in_days
+        if public_key is not None:
+            body['publicKey'] = _public_only(public_key)
+        if public_keys is not None:
+            body['publicKeys'] = [_public_only(k) for k in public_keys]
+        return self._http.post('/agents', body)['agent']
+
+    def list(self, status: Optional[str] = None) -> Dict[str, Any]:
+        """``{'agents': [...], 'killSwitch': {...}}``."""
+        return self._http.get('/agents', {'status': status} if status else None)
+
+    def get(self, agent_id: str) -> Dict[str, Any]:
+        return self._http.get(f'/agents/{_id(agent_id)}')['agent']
+
+    def update(self, agent_id: str, name: Optional[str] = None, description: Optional[str] = None,
+               owner_email: Optional[str] = None, platform: Optional[str] = None,
+               allowed_types: Optional[List[str]] = None, review_in_days: Optional[int] = None) -> Dict[str, Any]:
+        """Changes, hands over (``owner_email``) or renews (``review_in_days``) an agent."""
+        body: Dict[str, Any] = {}
+        for key, value in (('name', name), ('description', description), ('ownerEmail', owner_email),
+                           ('platform', platform), ('allowedTypes', allowed_types), ('reviewInDays', review_in_days)):
+            if value is not None:
+                body[key] = value
+        return self._http.patch(f'/agents/{_id(agent_id)}', body)['agent']
+
+    def add_key(self, agent_id: str, public_key: Dict[str, Any]) -> Dict[str, Any]:
+        """Adds a key (rotation: add the new one, move the agent to it, then remove the old one)."""
+        return self._http.post(f'/agents/{_id(agent_id)}/keys', {'publicKey': _public_only(public_key)})['agent']
+
+    def remove_key(self, agent_id: str, kid: str) -> Dict[str, Any]:
+        """Removes a key; tokens the agent got with it stop at once."""
+        return self._http.delete(f'/agents/{_id(agent_id)}/keys/{_id(kid)}')['agent']
+
+    def suspend(self, agent_id: str, reason: Optional[str] = None) -> Dict[str, Any]:
+        """Stops an agent at once (its tokens too) until resumed."""
+        return self._http.post(f'/agents/{_id(agent_id)}/suspend', {'reason': reason} if reason else {})['agent']
+
+    def resume(self, agent_id: str) -> Dict[str, Any]:
+        return self._http.post(f'/agents/{_id(agent_id)}/resume', {})['agent']
+
+    def revoke(self, agent_id: str) -> Dict[str, Any]:
+        """Revokes an agent for good (the record stays for the audit trail)."""
+        return self._http.delete(f'/agents/{_id(agent_id)}')['agent']
+
+    def set_policy(self, agent_id: str, policy: Dict[str, Any]) -> Dict[str, Any]:
+        """Sets the agent's budgets, amounts, recipients and background rule (a
+        full replacement; left-out fields take the defaults): requestsPer10Min,
+        requestsPerUserPer10Min, amountPerRequest / amountPerDay ({'TRY': '1000.00'}),
+        background ('non_critical' | 'never'), newRecipients ('ask' | 'deny'),
+        recipientAllowlist (IBANs / account numbers), fourEyes, requirePasskeyAbove
+        ({'TRY': '10000.00'}: over it the person approves with a passkey on your
+        page, never on the phone or with a mandate)."""
+        return self._http.put(f'/agents/{_id(agent_id)}/policy', {'policy': policy})['agent']
+
+    def list_events(self, after: Optional[str] = None, since: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        """The workspace's agent events for a SIEM, oldest first: ``{'events', 'next',
+        'hasMore'}``. Keep ``next`` and pass it as ``after``; the first call reads from
+        ``since`` (ISO 8601; default the last 24 hours)."""
+        params: Dict[str, Any] = {}
+        for key, value in (('after', after), ('since', since), ('limit', limit)):
+            if value is not None:
+                params[key] = value
+        return self._http.get('/agents/events', params or None)
+
+    def get_workspace_policy(self) -> Dict[str, Any]:
+        """The workspace's policy: every agent's floor (an agent's own policy can only make it stricter)."""
+        return self._http.get('/agents/workspace-policy')['policy']
+
+    def set_workspace_policy(self, policy: Dict[str, Any]) -> Dict[str, Any]:
+        """Sets the workspace's policy (a full replacement; a field left out sets no floor)."""
+        return self._http.put('/agents/workspace-policy', {'policy': policy})['policy']
+
+    def list_blocks(self, agent_id: str) -> List[Dict[str, Any]]:
+        """The people who stopped this agent asking them (reason not_me, coached or rejections)."""
+        return self._http.get(f'/agents/{_id(agent_id)}/blocks')['blocks']
+
+    def lift_block(self, agent_id: str, user: str) -> None:
+        """Lets the agent ask this person again (check with them first)."""
+        self._http.delete(f'/agents/{_id(agent_id)}/blocks/{_id(user)}')
+
+    def list_mandates(self, agent_id: str, user: Optional[str] = None) -> List[Dict[str, Any]]:
+        """An agent's mandates, optionally one person's."""
+        return self._http.get(f'/agents/{_id(agent_id)}/mandates', {'externalUsername': user} if user else None)['mandates']
+
+    def revoke_mandate(self, agent_id: str, mandate_id: str) -> Dict[str, Any]:
+        """Ends an agent's mandate at once."""
+        return self._http.post(f'/agents/{_id(agent_id)}/mandates/{_id(mandate_id)}/revoke', {})
+
+    def set_kill_switch(self, engaged: bool, reason: Optional[str] = None) -> Dict[str, Any]:
+        """Stops (True) or restarts (False) every agent of the workspace at once."""
+        body: Dict[str, Any] = {'engaged': engaged}
+        if reason:
+            body['reason'] = reason
+        return self._http.put('/agents/kill-switch', body)['killSwitch']

touchque/resources/assist.py

@@ -0,0 +1,115 @@
+"""Help desk: IT working on a person's account in the open.
+
+1. Before your help desk acts on someone's account: ``open`` with the person
+   and the signed-in agent. The person's phone gets a calm notice ("<agent>
+   from IT is working on your account now"); while the session is open, their
+   "someone says they're from IT" button shows this agent, and with none open
+   it tells them to hang up (webhook ``ASSIST_CLAIM_UNVERIFIED``).
+2. Before a sensitive action (a factor or password reset, an activation or
+   recovery link, an unlock, a new phone, removing a passkey): ``verify``. Show
+   ``challengeCode`` to the agent only; they read it to the person, who types
+   it on their phone and approves with Face ID. Default deny.
+3. Right before the action: ``spend`` (a passed check, for that action, at most
+   ten minutes old, once). ``unfreeze`` lifts a freeze the same way.
+
+No phone (``code`` ``no_phone``, ``data['route']`` ``never_locked_out``): the
+person moves to a new phone with Never Locked Out; the help desk cannot.
+"""
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from ..exceptions import TouchQueConfigException
+from ..http_client import HttpClient
+
+
+def _path(id: str, rest: str = '') -> str:
+    return f'/assist/{quote(id, safe="")}{rest}'
+
+
+def is_assist_check_passed(session: Dict[str, Any], request_id: str) -> bool:
+    """The check of ``request_id`` passed on the person's phone and was not used yet."""
+    for check in session.get('checks') or []:
+        if check.get('requestId') == request_id:
+            return check.get('outcome') == 'verified' and not check.get('spentAt')
+    return False
+
+
+class Assist:
+    """IT working on a person's account, and checks on their phone before sensitive actions."""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def open(self, external_username: str, agent: Dict[str, str], reason: Optional[str] = None,
+             ttl_minutes: Optional[int] = None, notify: Optional[bool] = None) -> Dict[str, Any]:
+        """Starts helping a person. ``agent``: ``{'name', 'title', 'ref'}`` (``ref`` is your id for them).
+        A session of the same agent for the same person is replaced."""
+        if not external_username or not (agent or {}).get('name'):
+            raise TouchQueConfigException('assist.open() needs external_username and agent["name"]')
+        payload: Dict[str, Any] = {'externalUsername': external_username, 'agent': {k: v for k, v in agent.items() if v}}
+        if reason:
+            payload['reason'] = reason
+        if ttl_minutes is not None:
+            payload['ttlMinutes'] = ttl_minutes
+        if notify is not None:
+            payload['notify'] = notify
+        return self._http.post('/assist', payload)
+
+    def get(self, id: str) -> Dict[str, Any]:
+        """The session and its checks. Poll it while a check is ``pending``."""
+        if not id:
+            raise TouchQueConfigException('assist.get() needs the session id')
+        return self._http.get(_path(id))
+
+    def list(self, external_username: Optional[str] = None, open_only: bool = False,
+             open: Optional[bool] = None) -> List[Dict[str, Any]]:
+        """A person's sessions, or every open one, newest first.
+        ``open=True`` is the same as ``open_only=True`` (the name ``recovery.list`` and the other SDKs use)."""
+        open_only = open_only or bool(open)
+        if not external_username and not open_only:
+            raise TouchQueConfigException('assist.list() needs external_username or open_only=True')
+        params: Dict[str, Any] = {}
+        if external_username:
+            params['externalUsername'] = external_username
+        if open_only:
+            params['open'] = 'true'
+        res = self._http.get('/assist', params)
+        return list((res or {}).get('sessions') or [])
+
+    def verify(self, id: str, action: str, action_text: Optional[str] = None,
+               details: Optional[List[Dict[str, str]]] = None) -> Dict[str, Any]:
+        """Asks the person's phone to confirm ``action`` (``reset_2fa``, ``reset_password``, ``activation_link``,
+        ``recovery_link``, ``unlock``, ``new_phone``, ``remove_passkey`` or your own). Returns ``requestId`` and
+        ``challengeCode`` (for the agent only). Raises TouchQueAPIException ``no_phone``, ``assist_not_open`` or
+        ``rate_limited``."""
+        if not id or not action:
+            raise TouchQueConfigException('assist.verify() needs the session id and an action')
+        payload: Dict[str, Any] = {'action': action}
+        if action_text:
+            payload['actionText'] = action_text
+        if details:
+            payload['details'] = details
+        return self._http.post(_path(id, '/verify'), payload)
+
+    def spend(self, id: str, request_id: str, action: str) -> Dict[str, Any]:
+        """Uses a passed check for its action, right before you take it; ``check_required`` (428) otherwise."""
+        if not id or not request_id or not action:
+            raise TouchQueConfigException('assist.spend() needs the session id, request_id and action')
+        return self._http.post(_path(id, '/spend'), {'requestId': request_id, 'action': action})
+
+    def unfreeze(self, id: str, request_id: str) -> Dict[str, Any]:
+        """Lifts the person's approval freeze with a passed check for ``unlock``: ``{'unfrozen', 'session'}``."""
+        if not id or not request_id:
+            raise TouchQueConfigException('assist.unfreeze() needs the session id and request_id')
+        return self._http.post(_path(id, '/unfreeze'), {'requestId': request_id})
+
+    def end(self, id: str, by: Optional[str] = None, reason: Optional[str] = None) -> Dict[str, Any]:
+        """Stops helping; checks still waiting on the phone expire."""
+        if not id:
+            raise TouchQueConfigException('assist.end() needs the session id')
+        payload: Dict[str, Any] = {}
+        if by:
+            payload['by'] = by
+        if reason:
+            payload['reason'] = reason
+        return self._http.post(_path(id, '/end'), payload)