esp-morpheus 0.9.0__py3-none-any.whl

esp_morpheus/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""esp-morpheus: the console client for an ESP RainMaker Neo deployment."""
+
+__version__ = '0.9.0'

esp_morpheus/cli/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0

esp_morpheus/cli/admin/__init__.py

@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""`esp-morpheus admin ...` — every operation that needs AWS credentials or the admin API.
+
+One tree holds the whole privileged surface, so what an ordinary caller can reach is exactly what
+sits outside it: `user` and `device` go through the deployment's own API and broker and need no AWS
+account, while everything here either signs in against the admin pool or calls AWS directly.
+
+The identity is optional, because half of these commands need no identity at all — `ses`, `sns`,
+`bot-user` and `test-data` reach AWS, not the admin API.
+"""
+
+import os
+
+import boto3
+import click
+from botocore.exceptions import BotoCoreError, ClientError
+
+from .. import output
+from ..context import Session
+from ..guide import guide
+from ..shell import ContextGroup
+from . import (
+    botuser,
+    gendevice,
+    integrations,
+    messaging,
+    nodes,
+    platforms,
+    runtime,
+    testdata,
+)
+
+IDENTITY_HINT = ('name one with `esp-morpheus admin <identity>`, or seed one with '
+                 '`esp-morpheus admin test-data setup`.')
+
+# Where the group leaves the identity it took off the command line, for its own callback to read.
+IDENTITY_META = 'morpheus.admin.identity'
+
+
+def _configured_admin(session):
+    """The admin test_config.json flags, so the seeded deployment needs no identity."""
+    return next((u.get('name') for u in session.config.get('users', []) if u.get('admin')), None)
+
+
+def _deployment_row(session, settings):
+    """Which deployment every command here acts on."""
+    if settings is None:
+        return '[red]unresolved[/red]', session.settings_error
+    return f"{settings.account_id} / {settings.region}", _source_label(settings.source)
+
+
+def _source_label(source):
+    """The outputs file, written relative to the working directory when it sits below it."""
+    if source.startswith(('http://', 'https://')):
+        return source
+    relative = os.path.relpath(source)
+    return source if relative.startswith(os.pardir) else relative
+
+
+def _admin_api_row(session, identity, settings):
+    """The admin account as (value, note, username), the last being what the prompt is labelled with.
+
+    Sign-in is reported, not enforced: the AWS half of this tree runs without an admin account.
+    """
+    if not identity:
+        return '[yellow]none[/yellow]', IDENTITY_HINT, None
+    if settings is None:
+        return identity, 'not signed in: the deployment is unresolved', None
+    # Warn rather than abort: an admin that does not exist yet is created by `test-data setup`.
+    user = session.authenticated_user(on_failure='warn')
+    note = 'signed in' if getattr(user, 'token', None) else '[red]sign-in failed[/red]'
+    return f"[bold]{user.username}[/bold]", note, user.username
+
+
+def _aws_row():
+    """Where the ambient credentials come from, without spending an STS call to find out.
+
+    Resolving them for real would force credentials on a prompt whose admin-API half needs none.
+    """
+    try:
+        credentials = boto3.session.Session().get_credentials()
+    except (BotoCoreError, ClientError) as e:
+        return '[red]unusable[/red]', str(e)
+    if credentials is None:
+        return ('[yellow]none found[/yellow]',
+                'configure AWS_PROFILE, `aws sso login`, ~/.aws/credentials or the environment')
+    profile = os.environ.get('AWS_PROFILE')
+    source = getattr(credentials, 'method', None) or 'unknown source'
+    where = f"{source}, AWS_PROFILE={profile}" if profile else source
+    return where, 'account checked on the first AWS command'
+
+
+def _print_context(session, identity):
+    """Name both identities this context holds, and return the one the prompt is labelled with.
+
+    Every row is built before anything prints, so a password prompt cannot land inside the banner.
+    """
+    settings = session.try_settings()
+    api_value, api_note, username = _admin_api_row(session, identity, settings)
+    output.context_rows('Admin context', [
+        ('deployment', *_deployment_row(session, settings)),
+        ('admin API', api_value, api_note),
+        ('AWS creds', *_aws_row()),
+    ])
+    return username
+
+
+class AdminGroup(ContextGroup):
+    """`admin [IDENTITY] <command>`, where the identity may be left out.
+
+    click would read the first word as the identity and then find no command, so a first word that
+    names one of these commands is that command.
+    """
+
+    def parse_args(self, ctx, args):
+        if args and not args[0].startswith('-') and args[0] not in self.commands:
+            ctx.meta[IDENTITY_META] = args[0]
+            args = args[1:]
+        return super().parse_args(ctx, args)
+
+    def resolve_command(self, ctx, args):
+        """Report a word taken as the identity, which is what a mistyped command becomes here."""
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            identity = ctx.meta.get(IDENTITY_META)
+            if not identity:
+                raise
+            raise click.UsageError(
+                f"No such command {args[0]!r}. The first word is read as the identity "
+                f"({identity!r}), so the command follows it.", ctx=ctx) from None
+
+
+@click.group('admin', cls=AdminGroup, invoke_without_command=True,
+             options_metavar='', subcommand_metavar='[IDENTITY] [OPTIONS] COMMAND [ARGS]...',
+             repl_prompt='{label} > ', history='admin')
+@click.option('--password', help='Password for an identity that test_config.json does not carry. '
+                                 'Also read from RMNG_PASSWORD, else prompted for. Prefer either '
+                                 'over argv, which other processes and shell history can see.')
+@click.pass_context
+def admin(ctx, password):
+    """Administer the deployment, as IDENTITY where a command needs one.
+
+    IDENTITY is an admin: an email address, or an index or name in test_config.json. It defaults to
+    the admin test_config.json flags, and only the commands that call the admin API need one. With
+    no subcommand, this opens an interactive prompt.
+    """
+    session = ctx.find_object(Session)
+    session.is_admin = True
+    session.password = password
+    session.identity_hint = IDENTITY_HINT
+
+    identity = ctx.meta.get(IDENTITY_META) or _configured_admin(session)
+    if identity:
+        session.select_user(identity)
+    if ctx.invoked_subcommand is not None:
+        return
+
+    username = _print_context(session, identity)
+    ctx.command.open_shell(ctx, f"admin:{username}" if username else 'admin')
+
+
+# `guide` needs nothing itself: it prints the console half of a setup whose other half is here.
+for command in (botuser.bot_user, guide, integrations.integrations, messaging.ses, messaging.sns,
+                nodes.nodes, platforms.platforms, runtime.claiming, runtime.iot_event_mode,
+                testdata.test_data):
+    admin.add_command(command)
+
+# Same reason, one level down: the node it writes is inert until `test-data setup` registers it.
+testdata.test_data.add_command(gendevice.gen_device)

esp_morpheus/cli/admin/botuser.py

@@ -0,0 +1,212 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""`esp-morpheus admin bot-user ...` — the CI IAM user and its access keys."""
+
+import json
+
+import boto3
+import click
+from botocore.exceptions import ClientError
+
+from ... import paths
+from .. import output
+from ..context import pass_session
+
+ADMINISTRATOR_ACCESS_POLICY_ARN = 'arn:aws:iam::aws:policy/AdministratorAccess'
+
+# Name of the IAM user when nothing names one. The key holding a chosen name is written by
+# `bot-user create`, so no entry has to exist before the first run.
+DEFAULT_BOT_USER_NAME = 'bot'
+BOT_USER_CONFIG_KEY = 'ci_bot_user'
+
+
+@click.group('bot-user')
+def bot_user():
+    """Create and delete the CI IAM bot user.
+
+    One bot at a time: there is a single credentials file, so a second user under another name would
+    overwrite the keys of the first and leave it in IAM with nothing tracking its access key.
+    """
+
+
+def _credentials_owner():
+    """The user named by the credentials file, or None when there is no file and no usable name."""
+    path = paths.bot_credentials_path()
+    if not path.is_file():
+        return None
+    try:
+        with open(path, encoding='utf-8') as handle:
+            return json.load(handle).get('user_name') or None
+    except (OSError, ValueError):
+        return None
+
+
+def _tracked_bot_user_name(session):
+    """The bot this checkout already holds keys for, or None.
+
+    The credentials file answers first: it is the record that a create would overwrite.
+    """
+    return _credentials_owner() or session.config.get(BOT_USER_CONFIG_KEY) or None
+
+
+def _bot_user_name(session, name=None):
+    return name or _tracked_bot_user_name(session) or DEFAULT_BOT_USER_NAME
+
+
+def _remember_bot_user_name(session, name):
+    """Record the name so `delete` and `show` need no argument."""
+    if session.config.get(BOT_USER_CONFIG_KEY) == name:
+        return
+    session.config[BOT_USER_CONFIG_KEY] = name
+    session.write_config()
+
+
+def _forget_bot_user_name(session, name):
+    if session.config.get(BOT_USER_CONFIG_KEY) != name:
+        return
+    del session.config[BOT_USER_CONFIG_KEY]
+    session.write_config()
+
+
+def _iam_user_exists(iam, user_name):
+    try:
+        iam.get_user(UserName=user_name)
+        return True
+    except ClientError as e:
+        if e.response.get('Error', {}).get('Code') == 'NoSuchEntity':
+            return False
+        raise
+
+
+def _delete_access_keys(iam, name):
+    for page in iam.get_paginator('list_access_keys').paginate(UserName=name):
+        for meta in page.get('AccessKeyMetadata', []):
+            iam.delete_access_key(UserName=name, AccessKeyId=meta['AccessKeyId'])
+
+
+def _write_bot_credentials(name, key):
+    credentials_path = paths.bot_credentials_path()
+    paths.ensure(credentials_path.parent)
+    with open(credentials_path, 'w', encoding='utf-8') as handle:
+        json.dump({'user_name': name,
+                   'access_key_id': key['AccessKeyId'],
+                   'secret_access_key': key['SecretAccessKey']}, handle, indent=2)
+    try:
+        credentials_path.chmod(0o600)
+    except OSError:
+        pass
+    return credentials_path
+
+
+@bot_user.command('show')
+@click.argument('name', required=False)
+@pass_session
+def show_bot_user(session, name):
+    """Report the bot user's name, its IAM state and where its keys are."""
+    settings = session.require_aws()
+    name = _bot_user_name(session, name)
+    credentials_path = paths.bot_credentials_path()
+    iam = boto3.client('iam', region_name=settings.region)
+
+    tracked = _tracked_bot_user_name(session)
+    record = {'name': name, 'exists': _iam_user_exists(iam, name),
+              'credentials': str(credentials_path),
+              'credentials_present': credentials_path.is_file()}
+    if tracked and tracked != name:
+        # The keys on disk belong to somebody else, so they are not this user's.
+        record['credentials_belong_to'] = tracked
+    if record['exists']:
+        policies = iam.list_attached_user_policies(UserName=name).get('AttachedPolicies', [])
+        record['policies'] = [p['PolicyArn'] for p in policies] or ['(none)']
+        record['access_keys'] = sum(
+            len(page.get('AccessKeyMetadata', []))
+            for page in iam.get_paginator('list_access_keys').paginate(UserName=name))
+    output.emit_kv(None, record)
+
+
+@bot_user.command('create')
+@click.argument('name', required=False)
+@click.option('--rotate', is_flag=True,
+              help='Replace the keys of an existing user instead of failing.')
+@pass_session
+def create_bot_user(session, name, rotate):
+    """Create the IAM bot user with AdministratorAccess and write its access keys.
+
+    NAME defaults to the bot this checkout already tracks, then to "bot". The name used is saved
+    back to test_config.json, so `bot-user delete` needs no argument.
+    """
+    settings = session.require_aws()
+    name = _bot_user_name(session, name)
+    iam = boto3.client('iam', region_name=settings.region)
+    tracked = _tracked_bot_user_name(session)
+
+    # A second name would overwrite the one credentials file and strand the first user in IAM with
+    # a live AdministratorAccess key. A tracked name IAM no longer has is stale, so it does not bite.
+    if tracked and tracked != name and _iam_user_exists(iam, tracked):
+        output.fail(f"This checkout already tracks IAM user {tracked!r}, and there is one "
+                    f"credentials file. Run `esp-morpheus admin bot-user delete` before creating "
+                    f"{name!r}, or `esp-morpheus admin bot-user create {tracked} --rotate` to issue it "
+                    'a new key.')
+
+    exists = _iam_user_exists(iam, name)
+    if exists and not rotate:
+        output.fail(f"IAM user {name!r} already exists. Run `esp-morpheus admin bot-user create "
+                    '--rotate` to issue a new key, or `esp-morpheus admin bot-user delete` to remove '
+                    'the user.')
+    if exists:
+        # A rotate is the recovery path for a lost credentials file: IAM allows two keys per user,
+        # so clear the old ones before asking for another.
+        _delete_access_keys(iam, name)
+    else:
+        iam.create_user(UserName=name, Tags=[{'Key': 'Created-For', 'Value': 'Jenkins+CI'},
+                                             {'Key': 'Created-By', 'Value': 'Repository'}])
+    iam.attach_user_policy(UserName=name, PolicyArn=ADMINISTRATOR_ACCESS_POLICY_ARN)
+    key = iam.create_access_key(UserName=name)['AccessKey']
+
+    credentials_path = _write_bot_credentials(name, key)
+    _remember_bot_user_name(session, name)
+    output.ok(f"{'Rotated the key of' if exists else 'Created'} IAM user {name} with "
+              'AdministratorAccess')
+    output.emit_kv(None, {'credentials': str(credentials_path)})
+
+
+@bot_user.command('delete')
+@click.argument('name', required=False)
+@pass_session
+def delete_bot_user(session, name):
+    """Delete the IAM bot user, its access keys and the credentials file."""
+    settings = session.require_aws()
+    name = _bot_user_name(session, name)
+    credentials_path = paths.bot_credentials_path()
+    iam = boto3.client('iam', region_name=settings.region)
+
+    # The file is another bot's only when it names a different user. One naming nobody is unusable,
+    # so this command is the last chance to clear it.
+    owner = _credentials_owner()
+    owns_credentials = owner is None or owner == name
+
+    if not _iam_user_exists(iam, name):
+        output.info(f"IAM user {name!r} does not exist; nothing to destroy.")
+        if owns_credentials and credentials_path.is_file():
+            credentials_path.unlink()
+            output.ok(f"Removed {credentials_path}")
+        _forget_bot_user_name(session, name)
+        return
+
+    _delete_access_keys(iam, name)
+
+    try:
+        iam.detach_user_policy(UserName=name, PolicyArn=ADMINISTRATOR_ACCESS_POLICY_ARN)
+    except ClientError as e:
+        if e.response.get('Error', {}).get('Code') != 'NoSuchEntity':
+            raise
+
+    iam.delete_user(UserName=name)
+    _forget_bot_user_name(session, name)
+    if owns_credentials and credentials_path.is_file():
+        credentials_path.unlink()
+        output.ok(f"Deleted IAM user {name} and removed {credentials_path}")
+        return
+    output.ok(f"Deleted IAM user {name}")

esp_morpheus/cli/admin/gendevice.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""`esp-morpheus admin test-data gen-device` — a certificate and key for a node, generated locally.
+
+It reaches nothing and needs no credentials. It sits with `test-data` because it owns the same
+test_config.json, and the node it writes there does nothing until `test-data setup` registers it.
+"""
+
+import click
+
+from ...sdk.device import generate_key_and_cert
+from .. import output
+from ..context import pass_session
+
+
+@click.command('gen-device')
+@click.argument('node_name')
+@click.argument('key_type', type=click.Choice(['rsa', 'ec']))
+@click.option('--stdout', 'to_stdout', is_flag=True,
+              help='Print the certificate and key instead of writing test_config.json.')
+@click.option('--force', is_flag=True,
+              help='Replace the certificate when NODE_NAME is already in test_config.json.')
+@pass_session
+def gen_device(session, node_name, key_type, to_stdout, force):
+    """Generate a self-signed certificate and key for NODE_NAME.
+
+    Needs no deployment and no credentials. The node is appended to test_config.json, which is
+    written from the packaged defaults first when it does not exist yet. Register it with
+    `esp-morpheus admin test-data setup`, which re-runs idempotently over the nodes already seeded.
+    """
+    key_pem, cert_pem = generate_key_and_cert(node_name, key_type)
+    entry = {'thing_name': node_name, 'cert': cert_pem, 'key': key_pem}
+
+    if to_stdout:
+        output.emit_kv(None, entry)
+        return
+
+    if not session.config_exists():
+        session.generate_config()
+
+    nodes = session.config.setdefault('nodes', [])
+    index = next((i for i, n in enumerate(nodes) if n.get('thing_name') == node_name), None)
+    if index is None:
+        nodes.append(entry)
+        index = len(nodes) - 1
+        action = 'Added'
+    elif force:
+        # Updated, not replaced, so node_cfg and associate_to survive a certificate regeneration.
+        nodes[index].update(entry)
+        action = 'Regenerated the certificate of'
+    else:
+        output.fail(f"{node_name} is already node {index} in test_config.json. Pass --force to "
+                    'regenerate its certificate, which breaks the deployed node until the next '
+                    '`admin test-data setup`.')
+
+    path = session.write_config()
+    output.ok(f"{action} {node_name} as node {index}")
+    output.emit_kv(None, {'thing_name': node_name, 'key_type': key_type,
+                          'index': index, 'config': str(path)})

esp_morpheus/cli/admin/integrations.py

@@ -0,0 +1,211 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""`esp-morpheus admin integrations ...` — the voice-assistant credentials each skill needs."""
+
+import os
+
+import click
+
+from ...sdk import alexa_setup as alexa_smapi, gva_setup as gva_gcp
+from .. import output
+from ..context import Session, pass_session, pass_user
+from ..guide import print_alexa_instructions
+
+DEFAULT_ALEXA_CONFIG = 'alexa_skills_config.json'
+ALEXA_CONFIG_KEYS = ('smapi_client_id', 'smapi_client_secret', 'vendor_id',
+                     'smapi_refresh_token', 'redirect_urls', 'skill_name', 'skill_id')
+
+
+def _check_alexa_config(ctx, param, value):
+    """Reject a missing config before the command logs in, naming the keys the file needs."""
+    del ctx, param
+    if not os.path.isfile(value):
+        raise click.UsageError(
+            f'Alexa config not found: {value}\n'
+            f"Pass --config PATH, or write the file with these keys: "
+            f"{', '.join(ALEXA_CONFIG_KEYS)}")
+    return value
+
+
+def alexa_config_option(command):
+    """Attach the --config option every SMAPI command reads."""
+    return click.option(
+        '--config', 'config_file', default=DEFAULT_ALEXA_CONFIG, show_default=True,
+        type=click.Path(dir_okay=False), callback=_check_alexa_config, is_eager=True,
+        help='JSON file with the SMAPI credentials: ' + ', '.join(ALEXA_CONFIG_KEYS) + '.',
+    )(command)
+
+
+@click.group('integrations')
+def integrations():
+    """Configure the voice-assistant integrations."""
+
+
+@integrations.group('alexa')
+def alexa():
+    """Alexa smart-home skill configuration.
+
+    The SMAPI commands (setup-auto, list-skills, delete-skill) take `--config FILE`, which defaults
+    to alexa_skills_config.json. The setup command takes its own file as an argument.
+    """
+
+
+def _alexa_config_to_env(session, config_file):
+    """Populate the env the SMAPI helper reads, so one config file drives both halves.
+
+    Example alexa_skills_config.json:
+        {"smapi_client_id": "...", "smapi_client_secret": "...",
+         "skill_name": "ESP RainMaker", "skill_id": "amzn1.ask.skill.xxxx"}
+    """
+    config = output.read_json_file(config_file, 'Alexa config')
+    env_map = {
+        'SMAPI_CLIENT_ID': 'smapi_client_id',
+        'SMAPI_CLIENT_SECRET': 'smapi_client_secret',
+        'SMAPI_VENDOR_ID': 'vendor_id',
+        'SMAPI_REFRESH_TOKEN': 'smapi_refresh_token',
+        'ALEXA_REDIRECT_URLS': 'redirect_urls',
+    }
+    for env_key, config_key in env_map.items():
+        value = config.get(config_key)
+        if value:
+            os.environ[env_key] = ','.join(value) if isinstance(value, list) else str(value)
+    # alexa_setup reads outputs itself, keyed off RMNG_OUTPUTS; point it at the source esp-morpheus
+    # resolved so --client-outputs applies there too.
+    os.environ['RMNG_OUTPUTS'] = session.settings.source
+    return config
+
+
+@alexa.command('setup')
+@click.argument('config_file', type=click.Path(exists=True, dir_okay=False))
+@click.pass_context
+def alexa_config(ctx, config_file):
+    """Store the Alexa skill credentials from CONFIG_FILE in the backend."""
+    session = ctx.find_object(Session)
+    config = output.read_json_file(config_file, 'Alexa config')
+    missing = [k for k in ('redirect_urls', 'alexa_client_id', 'alexa_client_secret', 'skill_id')
+               if not config.get(k)]
+    if missing:
+        output.fail(f"{config_file} is missing {', '.join(missing)}")
+
+    output.emit_response(session.user.alexa_post_configuration(
+        redirect_uris=config['redirect_urls'], client_id=config['alexa_client_id'],
+        client_secret=config['alexa_client_secret'], skill_id=config['skill_id']),
+        'Alexa configuration stored')
+    print_alexa_instructions(session.settings)
+
+
+@alexa.command('setup-auto')
+@alexa_config_option
+@click.argument('skill_name', nargs=-1)
+@click.pass_context
+def alexa_auto(ctx, config_file, skill_name):
+    """Create or update the skill over SMAPI, then store its configuration.
+
+    The config POST goes through this admin's session, so no separate AWS credentials are needed.
+    """
+    session = ctx.find_object(Session)
+    config = _alexa_config_to_env(session, config_file)
+
+    def post_config(skill_id, client_id, client_secret, redirect_uris):
+        output.emit_response(session.user.alexa_post_configuration(
+            redirect_uris=redirect_uris, client_id=client_id,
+            client_secret=client_secret, skill_id=skill_id), 'Alexa configuration stored')
+
+    alexa_smapi.setup(post_config, skill_id=config.get('skill_id'),
+                      skill_name=' '.join(skill_name) or config.get('skill_name'))
+
+
+@alexa.command('list-skills')
+@alexa_config_option
+@pass_session
+def alexa_list(session, config_file):
+    """List every Alexa skill under the vendor."""
+    _alexa_config_to_env(session, config_file)
+    alexa_smapi.list_all()
+
+
+@alexa.command('delete-skill')
+@click.argument('skill_id')
+@alexa_config_option
+@pass_session
+def alexa_delete(session, skill_id, config_file):
+    """Delete the Alexa skill SKILL_ID."""
+    _alexa_config_to_env(session, config_file)
+    alexa_smapi.delete(skill_id)
+
+
+@integrations.group('gva')
+def gva():
+    """Google Home integration."""
+
+
+@gva.command('setup')
+@click.argument('service_account_json', type=click.Path(exists=True, dir_okay=False))
+@click.pass_context
+def gva_setup(ctx, service_account_json):
+    """Upload the HomeGraph service-account key in SERVICE_ACCOUNT_JSON."""
+    session = ctx.find_object(Session)
+    config = output.read_json_file(service_account_json, 'service account')
+    output.emit_response(session.user.gva_post_configuration(config),
+                         'Google Home configuration stored')
+
+
+@gva.command('setup-auto')
+@click.argument('project_id')
+@click.argument('service_account_name', required=False)
+@pass_user
+def gva_auto(user, project_id, service_account_name):
+    """Enable the HomeGraph API, create the report-state service account and key on PROJECT_ID,
+    then store the key.
+
+    Replaces the console procedure in the spec (enable API, create account, grant the OpenID
+    Connect Identity Token Creator role, download a key, re-upload it). The Google-side work runs
+    locally against your `gcloud` credentials; only the config POST goes through this admin's
+    session, so no separate AWS credentials are needed.
+
+    The Google Home Developer Console part (creating the Home project and the cloud-to-cloud
+    integration) has no public API and stays manual.
+    """
+    def post_config(service_account_json):
+        output.emit_response(user.gva_post_configuration(service_account_json),
+                             'Google Home configuration stored')
+
+    gva_gcp.setup(post_config, project_id, service_account_name)
+
+
+@integrations.group('smartthings')
+def smartthings():
+    """SmartThings Schema App integration."""
+
+
+@smartthings.command('setup')
+@click.argument('config_file', type=click.Path(exists=True, dir_okay=False))
+@pass_user
+def st_setup(user, config_file):
+    """Store the credentials SmartThings issued, read from CONFIG_FILE.
+
+    Read from a file rather than argv: the client secret is 512 characters, and a secret in argv is
+    visible to other processes and lands in shell history.
+    """
+    config = output.read_json_file(config_file, 'SmartThings config')
+    missing = [field for field in ('client_id', 'client_secret') if not config.get(field)]
+    if missing:
+        output.fail(f"{config_file} is missing {', '.join(missing)}")
+    output.emit_response(user.st_post_configuration(config['client_id'], config['client_secret']),
+                         'SmartThings configuration stored')
+
+
+@smartthings.command('get-config')
+@pass_user
+def st_get(user):
+    """Show the stored SmartThings configuration."""
+    output.emit_response(user.st_get_configuration())
+
+
+@smartthings.command('delete-config')
+@pass_user
+def st_delete(user):
+    """Delete the stored SmartThings configuration."""
+    output.emit_response(user.st_delete_configuration(), 'SmartThings configuration deleted')