queryapigate 0.26.0__tar.gz → 0.28.0__tar.gz

{queryapigate-0.26.0/queryapigate.egg-info → queryapigate-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.26.0
+Version: 0.28.0
 Summary: Turn SQL into governed REST APIs over MySQL, PostgreSQL, ClickHouse, SQLite, DuckDB, H2, MongoDB, and Parquet/CSV/JSON files - JSON, CSV, Parquet or Excel out, with scoped keys, an admin Console and MCP for AI agents.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
 License-Expression: FSL-1.1-MIT
@@ -58,12 +58,15 @@ Requires-Dist: opentelemetry-sdk>=1.27; extra == "otel"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == "otel"
 Provides-Extra: server
 Requires-Dist: gunicorn>=21; extra == "server"
+Provides-Extra: aws
+Requires-Dist: boto3>=1.28; extra == "aws"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material<10,>=9; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: queryapigate[all]; extra == "dev"
 Requires-Dist: queryapigate[redis]; extra == "dev"
 Requires-Dist: queryapigate[otel]; extra == "dev"
+Requires-Dist: queryapigate[aws]; extra == "dev"
 Requires-Dist: queryapigate[mcp]; python_version >= "3.10" and extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: openapi-spec-validator>=0.7; extra == "dev"

{queryapigate-0.26.0 → queryapigate-0.28.0}/pyproject.toml

@@ -48,8 +48,12 @@ all = ["queryapigate[mysql,postgres,clickhouse,h2,duckdb,mongo,flow,encryption,j
 # only needed when an OTLP endpoint is set (OTEL_EXPORTER_OTLP_ENDPOINT) - see tracing.py
 otel = ["opentelemetry-sdk>=1.27", "opentelemetry-exporter-otlp-proto-http>=1.27"]
 server = ["gunicorn>=21"]
+# only needed for ${aws-sm:...} and aws-rds-iam credentials (ADR 0015) - see aws.py. 1.28 is the floor because that is
+# where boto3 reads AWS_ENDPOINT_URL_<SERVICE> (a VPC endpoint, or a local stand-in).
+aws = ["boto3>=1.28"]
 docs = ["mkdocs-material>=9,<10"]
-dev = ["queryapigate[all]", "queryapigate[redis]", "queryapigate[otel]", "queryapigate[mcp]; python_version>='3.10'",
+dev = ["queryapigate[all]", "queryapigate[redis]", "queryapigate[otel]", "queryapigate[aws]",
+       "queryapigate[mcp]; python_version>='3.10'",
       "ruff>=0.5",
       "openapi-spec-validator>=0.7", "hypothesis>=6.100", "mypy>=1.10", "coverage>=7.4"]
 

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/__init__.py

@@ -1,5 +1,5 @@
 """QueryAPIGate - expose SQL databases as a REST API."""
-__version__ = "0.26.0"
+__version__ = "0.28.0"
 
 from .app import create_app  # noqa: E402  (app imports __version__)
 

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/adminroles.py

@@ -33,12 +33,13 @@ CAPABILITIES = {
     'exports.write': 'create, change and delete exports',
     'exports.run': 'run an export',
     'destinations.write': 'create, change, test and delete destinations',
+    'config.apply': 'see what a configuration file would change, and apply it - any of the above (ADR 0014)',
 }
 
 _EVERYONE = {'queries.read', 'connections.read', 'observe', 'self'}
 ROLES = {
     'owner': set(CAPABILITIES),
-    'admin': set(CAPABILITIES) - {'admins.read', 'admins.write', 'secrets.rotate'},
+    'admin': set(CAPABILITIES) - {'admins.read', 'admins.write', 'secrets.rotate', 'config.apply'},
     'developer': _EVERYONE | {'queries.write', 'exports.read', 'exports.run'},
     'auditor': _EVERYONE | {'access.read', 'settings.read', 'exports.read'},
 }
@@ -90,6 +91,7 @@ OPERATIONS = {
     'v1.list_exports': 'exports.read', 'v1.get_export': 'exports.read', 'v1.list_export_runs': 'exports.read',
     'v1.create_export': 'exports.write', 'v1.update_export': 'exports.write', 'v1.delete_export': 'exports.write',
     'v1.run_export': 'exports.run',
+    'v1.config_diff': 'config.apply', 'v1.config_apply': 'config.apply', 'v1.config_managed': 'observe',
 }
 
 

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/alerts.py

@@ -58,7 +58,7 @@ KINDS = ('open_server', 'break_glass_used', 'connection_failing', 'key_expired',
          'query_timeouts', 'query_slow', 'key_rate_limited', 'client_rate_limited', 'history_failed', 'history_dropped',
          'instances_not_shared', 'instances_versions_differ', 'rate_limits_not_shared', 'export_failing', 'key_unused',
          'agent_unusual_volume', 'sso_unreachable', 'writes_awaiting_approval', 'encryption_key_rotation_incomplete',
-         'quota_nearly_used', 'audit_chain_broken', 'audit_delivery_behind')
+         'quota_nearly_used', 'audit_chain_broken', 'audit_delivery_behind', 'secret_provider_failing')
 
 
 def _alert(severity, kind, subject, title, detail, target=None, since=None):
@@ -75,7 +75,8 @@ def _plural(n, word):
 def collect(now=None):
     """Every alert that holds now, most severe first."""
     now = now or datetime.now()
-    found = [*_server(now), *_sso(), *_encryption(), *_audit_chain(), *_audit_delivery(now), *_writes(),
+    found = [*_server(now), *_sso(), *_encryption(), *_secret_providers(), *_audit_chain(), *_audit_delivery(now),
+             *_writes(),
              *_quotas(), *_keys(now), *_runs(now), *_rate_limited(), *_history_health()]
     return sorted(found, key=lambda a: (SEVERITY_ORDER[a['severity']], a['kind'], a['id']))
 
@@ -120,6 +121,25 @@ def _encryption():
                    'the first. Remove the others from every instance to finish the rotation.', target)]
 
 
+def _secret_providers():
+    """A secret provider - a file, Vault, AWS - failing for five minutes in this process (ADR 0015): connections whose
+    secrets come from it work only while the values it gave before are within their time, then fail."""
+    import time
+
+    from . import secretrefs
+    found = []
+    for name, status in sorted(secretrefs.cache.status.items()):
+        since = status.get('failing_since')
+        if since is None or time.time() - since < 300:
+            continue
+        stamp = f'{datetime.fromtimestamp(since):%Y-%m-%d %H:%M:%S}'
+        found.append(_alert('critical', 'secret_provider_failing', name, f'The secret provider {name} is failing',
+                            f"It has failed since {stamp}: {status.get('last_error')}. Connections that take a secret "
+                            'from it work only while what it gave before is within its time; then they fail with '
+                            'secret_unavailable.', {'type': 'settings', 'name': 'security'}, stamp))
+    return found
+
+
 def _audit_chain():
     """The audit log's hash chain doesn't verify (ADR 0012): an entry changed, removed, inserted or reordered."""
     from . import auditchain

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/apikeys.py

@@ -417,6 +417,29 @@ def _validate_allowed_tables(allowed_tables):
     return sorted({v.lower() for v in allowed_tables})
 
 
+def normalize_grants(connections=None, allow_writes=False, queries=None, collections=None, rate_limit=None,
+                     allowed_ips=None, allowed_write_ops=None, allowed_tables=None, mask=None, max_concurrent=None,
+                     query_timeout=None, max_rows=None, quota=None):
+    """A key's or role's grants, checked and normalised as they're stored - without writing anything, or checking that
+    the collections named exist (_require_existing_collections() does, where they're saved). The one place a grant's
+    rules are applied: creating a key or role, and reading one from a configuration file (configcode.py)."""
+    return {
+        'connections': _normalize_connections(connections),
+        'allow_writes': bool(allow_writes),
+        'queries': _normalize_queries(queries),
+        'collections': _normalize_collections(collections),
+        'rate_limit': _validate_rate_limit(rate_limit),
+        'allowed_ips': _validate_allowed_ips(allowed_ips),
+        'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
+        'allowed_tables': _validate_allowed_tables(allowed_tables),
+        'mask': masking.validate_rules(mask),
+        'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
+        'query_timeout': _validate_limit('query_timeout', query_timeout),
+        'max_rows': _validate_limit('max_rows', max_rows),
+        'quota': quotas.validate(quota),
+    }
+
+
 def is_expired(entry):
     """Whether a stored key entry's expires_at date has passed - checked live on every authenticate() call,
     not swept by a background job: an expired key simply stops matching, the same way flipping `active` to
@@ -476,6 +499,13 @@ def list_keys():
             for name, entry in _read().items()}
 
 
+def secret_hashes():
+    """{name: SHA-256 of the key's secret} - for a configuration file only (ADR 0014), which declares a key by its
+    hash. Not a secret: a generated secret is 32 random bytes, so its hash can't be reversed. The API never shows it
+    anyway, like the rest of what authenticates a key."""
+    return {name: entry['hash'] for name, entry in _read().items()}
+
+
 def create_key(name, connections=None, allow_writes=None, queries=None, expires_at=None, rate_limit=None,
                allowed_ips=None, allowed_write_ops=None, role=None, collections=None, allowed_tables=None,
                example=False, mask=None, max_concurrent=None, query_timeout=None, max_rows=None, quota=None):
@@ -517,20 +547,10 @@ def create_key(name, connections=None, allow_writes=None, queries=None, expires_
             raise ApiError(f"An API key named '{name}' already exists", 409, code='key_exists')
         entry = {
             'hash': _hash(secret),
-            'connections': _normalize_connections(connections),
-            'allow_writes': bool(allow_writes),
-            'queries': _normalize_queries(queries),
-            'collections': collections,
+            **normalize_grants(connections, allow_writes, queries, collections, rate_limit, allowed_ips,
+                               allowed_write_ops, allowed_tables, mask, max_concurrent, query_timeout, max_rows,
+                               quota),
             'expires_at': _validate_expiry(expires_at),
-            'rate_limit': _validate_rate_limit(rate_limit),
-            'allowed_ips': _validate_allowed_ips(allowed_ips),
-            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
-            'allowed_tables': _validate_allowed_tables(allowed_tables),
-            'mask': masking.validate_rules(mask),
-            'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
-            'query_timeout': _validate_limit('query_timeout', query_timeout),
-            'max_rows': _validate_limit('max_rows', max_rows),
-            'quota': quotas.validate(quota),
             'created_from_role': role,
             'active': True,
             'created_at': store.now(),
@@ -610,15 +630,45 @@ def rotate_key(name, grace_minutes=None):
                            '- end that first (DELETE .../previous), or wait for it', 409,
                            code='key_rotation_pending', previous_expires_at=row['previous_expires_at'])
         secret = 'sk_' + secrets.token_urlsafe(32)
-        until = (datetime.now() + timedelta(minutes=grace)).strftime('%Y-%m-%d %H:%M:%S') if grace else None
-        details = json.loads(row['details_json'])
-        details.pop('previous_last_used_at', None)
-        conn.execute('UPDATE api_keys SET hash = ?, previous_hash = ?, previous_expires_at = ?, details_json = ? '
-                     'WHERE name = ?', (_hash(secret), row['hash'] if until else None, until, json.dumps(details),
-                                        name))
+        until = _replace_hash(conn, name, row, _hash(secret), grace)
     return secret, until
 
 
+def _replace_hash(conn, name, row, new_hash, grace):
+    """The key's secret becomes the one `new_hash` is the hash of; the old one keeps working `grace` minutes."""
+    until = (datetime.now() + timedelta(minutes=grace)).strftime('%Y-%m-%d %H:%M:%S') if grace else None
+    details = json.loads(row['details_json'])
+    details.pop('previous_last_used_at', None)
+    conn.execute('UPDATE api_keys SET hash = ?, previous_hash = ?, previous_expires_at = ?, details_json = ? '
+                 'WHERE name = ?', (new_hash, row['hash'] if until else None, until, json.dumps(details), name))
+    return until
+
+
+def set_secret_hash(name, secret_hash, grace_minutes=None):
+    """A key's secret set to the one `secret_hash` is the SHA-256 of - a configuration file's `secret_sha256`
+    (ADR 0014) - with the old secret kept working for `grace_minutes`, as rotate_key() does. The secret itself is
+    never seen here. Refused when another key already has it: one secret must name one key. Returns when the old
+    secret stops working."""
+    grace = _validate_grace(grace_minutes)
+    with db.transaction() as conn:
+        row = conn.execute('SELECT hash, details_json, previous_hash, previous_expires_at FROM api_keys WHERE name = ?',
+                           (name,)).fetchone()
+        if row is None:
+            raise ApiError(f"API key '{name}' not found", 404, code='key_not_found')
+        taken = conn.execute('SELECT name FROM api_keys WHERE (hash = ? OR previous_hash = ?) AND name <> ?',
+                             (secret_hash, secret_hash, name)).fetchone()
+        if taken is not None:
+            raise ApiError("Another key already has this secret_sha256 - each key needs its own secret",
+                           409, code='key_secret_taken')
+        if row['hash'] == secret_hash:
+            return None
+        if grace and row['previous_hash'] and row['previous_expires_at'] and row['previous_expires_at'] > store.now():
+            raise ApiError(f"The secret this key had before its last change works until {row['previous_expires_at']} "
+                           '- end that first (DELETE .../previous), or wait for it', 409,
+                           code='key_rotation_pending', previous_expires_at=row['previous_expires_at'])
+        return _replace_hash(conn, name, row, secret_hash, grace)
+
+
 def end_previous(name):
     """Stop the old secret now, before its grace period ends. Returns when it would have stopped."""
     with db.transaction() as conn:
@@ -685,19 +735,9 @@ def create_role(name, connections=None, allow_writes=False, queries=None, rate_l
         if conn.execute('SELECT 1 FROM roles WHERE name = ?', (name,)).fetchone() is not None:
             raise ApiError(f"A role named '{name}' already exists", 409, code='role_exists')
         entry = {
-            'connections': _normalize_connections(connections),
-            'allow_writes': bool(allow_writes),
-            'queries': _normalize_queries(queries),
-            'collections': collections,
-            'rate_limit': _validate_rate_limit(rate_limit),
-            'allowed_ips': _validate_allowed_ips(allowed_ips),
-            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
-            'allowed_tables': _validate_allowed_tables(allowed_tables),
-            'mask': masking.validate_rules(mask),
-            'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
-            'query_timeout': _validate_limit('query_timeout', query_timeout),
-            'max_rows': _validate_limit('max_rows', max_rows),
-            'quota': quotas.validate(quota),
+            **normalize_grants(connections, allow_writes, queries, collections, rate_limit, allowed_ips,
+                               allowed_write_ops, allowed_tables, mask, max_concurrent, query_timeout, max_rows,
+                               quota),
             'created_at': store.now(),
             **({'example': True} if example else {}),  # installed by `examples load` - see examples.py
         }

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/app.py

@@ -91,6 +91,32 @@ class JSONProvider(DefaultJSONProvider):
     sort_keys = False  # keep result columns in the order the query returned them
 
 
+def apply_config_at_startup():
+    """QUERYAPIGATE_CONFIG_FILE (ADR 0014): apply it before serving - once per file, so with several instances the first
+    to start applies it and the others find it done. A file that can't be applied stops startup, changing nothing:
+    in a rolling update the new pods don't come up, and the ones still serving keep the configuration they have."""
+    from . import configcode
+    path = config.config_file()
+    if path is None:
+        return
+    try:
+        doc = configcode.load(path.read_text())
+        result = configcode.apply(doc, prune=config.config_prune(), actor='startup', once=True)
+    except OSError as error:
+        log.error('QUERYAPIGATE_CONFIG_FILE %s could not be read: %s', path, error)
+        raise ValueError(f'QUERYAPIGATE_CONFIG_FILE {path} could not be read: {error}') from None
+    except configcode.ConfigInvalid as error:
+        message = f'QUERYAPIGATE_CONFIG_FILE {path} was not applied - nothing in it was. ' + '; '.join(error.problems)
+        log.error('%s', message)  # one line in the log, whatever prints the exception after (gunicorn: a traceback)
+        raise ValueError(message) from None
+    if result.get('already_applied'):
+        log.info('QUERYAPIGATE_CONFIG_FILE %s (sha256 %s) is already applied', path, result['file_sha256'][:12])
+    else:
+        counts = {a: sum(1 for c in result['changes'] if c['action'] == a) for a in ('create', 'update', 'delete')}
+        log.info('Applied QUERYAPIGATE_CONFIG_FILE %s (sha256 %s): %d created, %d changed, %d deleted', path,
+                 result['file_sha256'][:12], counts['create'], counts['update'], counts['delete'])
+
+
 def load_examples_at_startup():
     """QUERYAPIGATE_LOAD_EXAMPLES=yes: make sure the example APIs are installed. A problem (something of yours
     holds an example's name, the home is read-only) is a warning, not a startup failure - the examples are a
@@ -190,6 +216,7 @@ def create_app():
     _note_audit_key_rotation()
     from . import auditstream
     auditstream.start()  # the audit log to a SIEM, when an output is set (ADR 0012)
+    apply_config_at_startup()
     if config.load_examples():
         load_examples_at_startup()
     app.json = JSONProvider(app)

queryapigate-0.28.0/queryapigate/aws.py

@@ -0,0 +1,85 @@
+"""AWS (ADR 0015): what `${aws-sm:...}` references and `aws-rds-iam` credentials resolve through - Secrets Manager, and
+IAM authentication tokens for RDS and Aurora.
+
+Through boto3 (the `aws` extra), with the standard credential chain - IRSA on EKS, an instance or task role, the usual
+AWS_* environment variables - and region (QUERYAPIGATE_AWS_REGION, else AWS_REGION and the rest of the chain).
+boto3's own AWS_ENDPOINT_URL_SECRETS_MANAGER points it elsewhere, for a VPC endpoint or a local stand-in.
+
+Nothing here decides what may be read - secretrefs.py checks QUERYAPIGATE_AWS_SECRET_PREFIXES and
+QUERYAPIGATE_AWS_RDS_HOSTS first.
+"""
+import json
+import threading
+
+from . import config
+
+RDS_TOKEN_SECONDS = 900  # an IAM authentication token is good for 15 minutes
+
+
+class AwsError(Exception):
+    """What AWS, or reaching it, refused - the message names why, never a secret."""
+
+
+_clients: dict[str, object] = {}
+_lock = threading.Lock()
+
+
+def _client(service):
+    with _lock:
+        if service not in _clients:
+            try:
+                import boto3
+            except ImportError:
+                raise AwsError('the "boto3" package is not installed - pip install "queryapigate[aws]"') from None
+            _clients[service] = boto3.client(service, region_name=config.aws_region())
+        return _clients[service]
+
+
+def reset():
+    with _lock:
+        _clients.clear()
+
+
+def _failure(error):
+    """An AWS error as a sentence: its code and message, never what was asked for in full."""
+    response = getattr(error, 'response', None) or {}
+    code = (response.get('Error') or {}).get('Code')
+    message = (response.get('Error') or {}).get('Message') or str(error)
+    return f'{code}: {message}' if code else message
+
+
+def secret(secret_id, field=None):
+    """A Secrets Manager secret's SecretString - or, with `field`, that field of its JSON: (value, None)."""
+    try:
+        answer = _client('secretsmanager').get_secret_value(SecretId=secret_id)
+    except AwsError:
+        raise
+    except Exception as error:  # botocore's ClientError, or one of its connection errors
+        raise AwsError(_failure(error)) from None
+    text = answer.get('SecretString')
+    if text is None:
+        raise AwsError(f'{secret_id} holds binary data, not text')
+    if field is None:
+        return text, None
+    try:
+        data = json.loads(text)
+    except ValueError:
+        raise AwsError(f"{secret_id} isn't JSON, so it has no field '{field}'") from None
+    if not isinstance(data, dict) or field not in data:
+        raise AwsError(f"{secret_id} has no field '{field}'")
+    if not isinstance(data[field], str):
+        raise AwsError(f"{secret_id}#{field} isn't text")
+    return data[field], None
+
+
+def rds_token(host, port, user):
+    """An IAM authentication token for `user` on the database at host:port - signed here, from the server's own AWS
+    credentials, with no call to AWS: ((user, token), seconds it lasts)."""
+    try:
+        region = {'Region': config.aws_region()} if config.aws_region() else {}  # else the client's own region
+        token = _client('rds').generate_db_auth_token(DBHostname=host, Port=int(port), DBUsername=user, **region)
+    except AwsError:
+        raise
+    except Exception as error:  # no credentials, no region
+        raise AwsError(_failure(error)) from None
+    return (user, token), RDS_TOKEN_SECONDS

{queryapigate-0.26.0 → queryapigate-0.28.0}/queryapigate/cli.py

@@ -2,9 +2,12 @@
 ``collection export|import``."""
 import argparse
 import contextlib
+import hashlib
 import json
 import logging
 import os
+import secrets
+import signal
 import sys
 import time
 from datetime import datetime, timedelta
@@ -15,6 +18,7 @@ from . import (
     admins,
     bundle,
     config,
+    configcode,
     db,
     examples,
     experimental,
@@ -41,6 +45,9 @@ def _serve(args):
             'Listening on %s without QUERYAPIGATE_API_KEY set: anyone who can reach this port can run SQL '
             'on your active connections.', args.host)
     logging.getLogger('queryapigate').info('Using %s (metadata: %s)', config.home(), db.describe())
+    # SIGTERM - what a container runtime or `kill` sends - as a clean exit, so what runs at exit does: Vault leases
+    # revoked (ADR 0015), the audit stream's lease given back. Python's default ends the process without it.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
     app.run(host=args.host, port=args.port, debug=args.debug, request_handler=_handler())
     return 0
 
@@ -333,6 +340,130 @@ def _collection_import(args):
     return 0
 
 
+def _config_command(action):
+    """Shared shell for the config subcommands (ADR 0014). Every failure exits 1, settings included: `config diff`
+    exits 2 for "there are changes", so a script can tell the two apart."""
+    def run(args):
+        try:
+            config.check_settings()
+            return action(args)
+        except configcode.ConfigInvalid as error:
+            print(f'queryapigate config {args.action}: {len(error.problems)} problem(s) in the file:', file=sys.stderr)
+            for problem in error.problems:
+                print(f'  {problem}', file=sys.stderr)
+            return 1
+        except ApiError as error:
+            print(f'queryapigate config {args.action}: {error.message}', file=sys.stderr)
+            return 1
+        except (OSError, ValueError) as error:
+            print(f'queryapigate config {args.action}: {error}', file=sys.stderr)
+            return 1
+    return run
+
+
+def _read_config_file(path):
+    if path == '-':
+        return configcode.load(sys.stdin.read())
+    with open(path) as f:
+        return configcode.load(f.read())
+
+
+@_config_command
+def _config_export(args):
+    kinds = tuple(k.strip() for k in args.kinds.split(',')) if args.kinds else configcode.KINDS
+    doc, variables, skipped = configcode.export(kinds, examples=args.examples)
+    text = configcode.dump(doc, variables)
+    if args.out is None:
+        sys.stdout.write(text)
+    else:
+        out_dir = os.path.dirname(args.out) or '.'
+        tmp_path = os.path.join(out_dir, f'.{os.path.basename(args.out)}.part')
+        try:
+            with open(tmp_path, 'w') as f:
+                f.write(text)
+            os.replace(tmp_path, args.out)  # a failed run never leaves a partial file at the destination
+        finally:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+        print(f'Wrote the configuration to {args.out}', file=sys.stderr)
+    for variable in variables:
+        print(f"Set {variable['name']} where the server runs: {variable['for']}'s password, stored "
+              f"{variable['stored']} here", file=sys.stderr)
+    for name in skipped:
+        print(f'Left out saved query {name}: it has no published version', file=sys.stderr)
+    return 0
+
+
+def _remote(args, operation, **flags):
+    """POST the file to a running server's /api/v1/config/<operation> (`--server`), with the key in QAG_API_KEY - an
+    environment variable, so it never shows in a CI log or a process list."""
+    import urllib.error
+    import urllib.request
+    key = os.environ.get('QAG_API_KEY', '').strip()
+    if not key:
+        raise ApiError('--server needs the API key in the QAG_API_KEY environment variable')
+    doc = _read_config_file(args.file)
+    query = '&'.join(f'{k}=true' for k, v in flags.items() if v)
+    url = args.server.rstrip('/') + f'/api/v1/config/{operation}' + (f'?{query}' if query else '')
+    request = urllib.request.Request(url, data=json.dumps(doc).encode(), method='POST',
+                                     headers={'X-API-Key': key, 'Content-Type': 'application/json'})
+    try:
+        with urllib.request.urlopen(request, timeout=120) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as error:
+        try:
+            body = json.load(error)
+        except ValueError:
+            raise ApiError(f'{url} answered {error.code}') from None
+        if body.get('code') == 'invalid_config':
+            raise configcode.ConfigInvalid(body.get('problems') or [body.get('error')]) from None
+        raise ApiError(f"{url} answered {error.code}: {body.get('error')}") from None
+    except urllib.error.URLError as error:
+        raise ApiError(f'{url}: {error.reason}') from None
+
+
+@_config_command
+def _config_diff(args):
+    if args.server:
+        result = _remote(args, 'diff', prune=args.prune)
+    else:
+        result = configcode.diff(_read_config_file(args.file), prune=args.prune)
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(configcode.render(result))
+    return 2 if result['changes'] else 0
+
+
+@_config_command
+def _config_apply(args):
+    if args.server:
+        result = _remote(args, 'apply', prune=args.prune, dry_run=args.dry_run)
+    elif args.dry_run:
+        result = {**configcode.diff(_read_config_file(args.file), prune=args.prune), 'applied': False}
+    else:
+        result = configcode.apply(_read_config_file(args.file), prune=args.prune, actor='cli')
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+    print(configcode.render(result))
+    if args.dry_run:
+        print('Dry run: nothing was changed.')
+    elif result['applied']:
+        print(f"Applied: the server matches the file (sha256 {result['file_sha256'][:12]}).")
+    return 0
+
+
+def _config_new_key(args):
+    """A fresh API key secret and its SHA-256, for a key declared in a configuration file. Nothing is stored."""
+    secret = 'sk_' + secrets.token_urlsafe(32)
+    print(f'secret:        {secret}')
+    print(f'secret_sha256: {hashlib.sha256(secret.encode()).hexdigest()}')
+    print('Give the secret to whoever uses the key, keep it in your secrets manager, and put only secret_sha256 in '
+          'the file.', file=sys.stderr)
+    return 0
+
+
 def _examples_command(action):
     """Shared shell for the examples subcommands - the same settings check and clean-error handling as the
     collection ones."""
@@ -686,6 +817,42 @@ def build_parser():
     collection_import.add_argument('--dry-run', action='store_true', help='report what would happen; write nothing')
     collection_import.set_defaults(func=_collection_import)
 
+    config_parser = commands.add_parser('config', help="the server's configuration as a file (ADR 0014, experimental): "
+                                                       'export it, see what applying one would change, apply it')
+    config_parser.set_defaults(func=lambda a: config_parser.print_help() or 2)
+    config_actions = config_parser.add_subparsers(dest='action')
+    config_export = config_actions.add_parser(
+        'export', help='write connections, destinations, roles, saved queries, API keys, descriptions and exports as '
+                       'one YAML file - passwords as ${VAR} references, keys as their hashes, never a secret')
+    config_export.add_argument('--kinds', help=f"only these, comma-separated (of: {', '.join(configcode.KINDS)})")
+    config_export.add_argument('--examples', action='store_true', help='include the bundled examples too')
+    config_export.add_argument('--out', help='write to this file instead of stdout')
+    config_export.set_defaults(func=_config_export)
+    config_diff = config_actions.add_parser(
+        'diff', help='what applying FILE would create and change, field by field - writes nothing. Exit 0: no '
+                     'changes; 2: changes; 1: the file has problems')
+    config_diff.add_argument('file', help='a configuration file (YAML or JSON), or - for stdin')
+    config_diff.add_argument('--json', action='store_true', help='the changes as JSON, for a script')
+    config_diff.add_argument('--prune', action='store_true', help='also show what --prune would delete')
+    config_diff.add_argument('--server', metavar='URL', help="a running server's base URL, instead of this home's "
+                                                             'store - the key in QAG_API_KEY (CI against prod)')
+    config_diff.set_defaults(func=_config_diff)
+    config_apply = config_actions.add_parser(
+        'apply', help='make the server match FILE, all or nothing - every change through the same rules as the API, '
+                      'audited; what the file does not name is left alone')
+    config_apply.add_argument('file', help='a configuration file (YAML or JSON), or - for stdin')
+    config_apply.add_argument('--prune', action='store_true',
+                              help='also delete what a file manages (created, changed or named before) and this one '
+                                   'no longer has - never what was made in the Console or the API')
+    config_apply.add_argument('--dry-run', action='store_true', help='say what would change; change nothing')
+    config_apply.add_argument('--json', action='store_true', help='the result as JSON, for a script')
+    config_apply.add_argument('--server', metavar='URL', help="a running server's base URL, instead of this home's "
+                                                              'store - the key in QAG_API_KEY (an owner\'s)')
+    config_apply.set_defaults(func=_config_apply)
+    config_new_key = config_actions.add_parser(
+        'new-key', help="a fresh API key secret and its secret_sha256, for a key declared in a file - nothing stored")
+    config_new_key.set_defaults(func=_config_new_key)
+
     example_parser = commands.add_parser('examples', help='load, remove or check the bundled example APIs '
                                                           '(reporting, dashboard, export, partner)')
     example_parser.set_defaults(func=lambda a: example_parser.print_help() or 2)
@@ -759,6 +926,8 @@ def main(argv=None):
         args = parser.parse_args(['serve', *(argv or [])])
     if getattr(args, 'home', None):
         os.environ['QUERYAPIGATE_HOME'] = args.home
+    if getattr(args, 'server', None) or getattr(args, 'func', None) is _config_new_key:
+        return args.func(args)  # nothing of this home's: no store opened, so none made in a CI checkout
     try:
         config.check_database_url()
         db.init_schema()