mkctl 0.4.0__tar.gz

mkctl-0.4.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node (web/)
+node_modules/
+.next/
+.turbo/
+
+# Local config and secrets — never tracked
+.env
+.env.*
+!.env.example
+deploy/.local/
+deploy/secrets/
+# Database dumps written by the pg-backup sidecar on the host
+deploy/backups/
+*.pem
+*.key
+!**/*.pub.key
+# age identities generated for laptop bring-up
+*.age
+
+# Runtime state
+.mklang-platform/
+*.db
+*.sqlite3
+run-artifacts/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

mkctl-0.4.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Gianluca
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mkctl-0.4.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mkctl
+Version: 0.4.0
+Summary: The command line for the control plane (ADR 0004)
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: mkp-contracts>=0.2.0

mkctl-0.4.0/README.md

@@ -0,0 +1,207 @@
+# mkctl — the command line for the control plane
+
+A human's terminal: it must not hold a password, and it must be revocable
+independently of the account ([ADR 0004](../../docs/adr/0004-delegated-authentication-owned-authorization.md)).
+It holds tokens the identity provider issued, and never a credential this platform
+minted.
+
+```
+mkctl login             browser, authorization code with PKCE
+mkctl login --device    no browser — SSH, containers, headless
+mkctl whoami            who the control plane thinks you are, and what you may do
+mkctl logout            revoke at the provider, then forget locally
+mkctl upgrade           print the procedure for the latest release (ADR 0014)
+
+mkctl bundle push ARCHIVE       register what `mkbundle build` produced, and upload it
+mkctl deploy DIGEST             point an environment at a bundle
+mkctl run start WORKFLOW        start a run; nothing executes in that request
+mkctl run list                  runs (filters; --environment not --env)
+mkctl run get RUN_ID            status, attempts, and what it is waiting on
+mkctl run reply RUN_ID          reply to a waiting run — the same act as the queue's Reply
+mkctl run abandon RUN_ID        cancel a waiting run
+
+mkctl project list|create       projects
+mkctl env list|create|get       environments, and what is deployed to one
+mkctl user list|create          who is in this tenant
+mkctl role grant|revoke         what they may do, and where
+mkctl tenant list|create        needs the platform grant, not a role
+mkctl connection list           credentials, by label (no values)
+mkctl connection create         static material, or authless when --material omitted (D10)
+mkctl connection bind NAME      what a workflow connection: name means in one env
+```
+
+Configured by `MKCTL_CONTROL_PLANE`, `MKCTL_OIDC_ISSUER`, `MKCTL_CLIENT_ID`, or the
+matching options. Endpoints are read from the provider's discovery document rather than
+configured: hard-coding paths would make an IdP change a code change, which is the
+coupling ADR 0004 spent an adapter to avoid.
+
+`--project` and `--env` (on deploy, run start, …) fall back to `MKCTL_PROJECT` and
+`MKCTL_ENVIRONMENT`, because a person works in one project all day. **`run list` takes
+`--environment`**, not `--env`. **A role's scope does not** default from those variables:
+`mkctl role grant ada@… owner` with no scope means the tenant, and an environment variable
+that quietly narrowed it to one project would make the same command grant different power
+on two machines.
+
+### On a laptop
+
+Prefer the wrapper so `MKCTL_*` come from `deploy/.local/env`:
+
+```bash
+./deploy/scripts/local mkctl login
+./deploy/scripts/local mkctl whoami
+```
+
+**Authless connections (`D10`):** omit every `--material` flag. The control plane still
+writes a vault envelope over an empty map — there is no plaintext path — and the runner
+never resolves material for `auth: kind: none`.
+
+Full laptop path (setup, demo, first_run, vendor):
+[`deploy/runbooks/local.md`](../../deploy/runbooks/local.md).
+
+`--json` on any command prints the control plane's own answer, for scripts. Everything
+else is formatted for a person, which mostly means saying what a state implies: a started
+run says nothing has executed yet, a created user says it has no roles, and a pushed
+bundle that is unsigned says a runner will refuse it (`D2`).
+
+## What this deliberately does not do
+
+**It does not build.** `mkbundle build` produces the archive and `mkctl bundle push`
+uploads it. Folding them together would make one command that fails for eight unrelated
+reasons — a missing connector catalog, `mklang check` on a machine, an expired login —
+and would put a signing key in the same process as a login token.
+
+**It does not compute a bundle's digest.** `POST /bundles` recomputes it from the manifest
+and returns it, and the archive is uploaded under the name the server gave back. A second
+opinion here would be a second definition of a bundle's identity, which is the thing
+`packages/mkp-contracts` exists to prevent. The one thing read locally is the manifest
+inside the archive, and that is read with `mkp_contracts.archive.manifest_of` for the same
+reason.
+
+**It does not guess a type.** `--input thread_id=t-1` sends a string, always;
+`--input-json '{"count": 2}'` is how anything else is expressed. A shell word carries no
+type, and inferring one would make `count=2` a number here and a string in the next tool
+that had the same idea slightly differently.
+
+## Two flows, and where PKCE actually applies
+
+**Authorization code with PKCE over a loopback redirect** (RFC 8252 §7.3, RFC 7636) is
+the default. The client holds no secret, and the `code_verifier` binds the code to the
+process that asked for it, so a code intercepted on its way back is useless. `state` is
+checked because a redirect is a request that anything on this machine could make.
+
+**The device authorization grant** (RFC 8628) is `--device`. It exists for the case the
+default cannot serve — a terminal over SSH, a container, a machine with no browser —
+which is every terminal that operates a remote runner, so it is not an edge case.
+
+ADR 0004 originally asked for "the device authorization flow with PKCE". That is two
+protections conflated: PKCE guards a redirect from interception, and the device grant
+has no redirect. Amendment 2 records the correction; the implementation does both flows
+and applies PKCE to the one that has something for it to protect.
+
+Neither flow uses a client secret. A secret shipped inside a CLI is a public value with
+a misleading name (RFC 8252 §8.5).
+
+## The rules the tests hold
+
+**`slow_down` lengthens the interval, it is not a retry.** RFC 8628 §3.5 says add at
+least five seconds. Treating it as "try again now" is how a client gets rate-limited
+into failing a flow that would otherwise have worked, and the symptom looks like the
+provider being flaky.
+
+**Whatever a refresh returns is what gets stored.** Providers rotate refresh tokens and
+enforce single use; a client that keeps the token it just sent turns that enforcement
+into a login loop on the day it is switched on. When a provider returns no new refresh
+token, the old one is kept rather than dropped — dropping it logs the user out on the
+first refresh.
+
+**Logout revokes before it forgets.** Deleting only the local copy leaves a live refresh
+token on a machine somebody may have just handed back, which is the opposite of
+"revocable per device".
+
+**Tokens go in the OS keyring, and nowhere else.** Where no keyring is available,
+`mkctl` refuses and says what to install. A CLI that degrades to a plaintext file when
+the keyring is missing is `nate`'s `TOKEN_ENCRYPTION_KEY` again: the safe path must not
+be the one that happens to be configured.
+
+One keyring entry per control plane, keyed by URL, so a laptop that talks to production
+and to a local stack does not have one login overwrite the other.
+
+## Known gap
+
+The device grant exists for machines without a browser, and those are also the machines
+least likely to have a Secret Service keyring — an SSH session on a bare server has
+neither. Today that combination cannot store a login, and `mkctl` says so rather than
+writing a file. The honest options are a keyring backend that works headless, or an ADR
+that widens where a token may live. It is in `ops/STATUS.md` as an open question rather
+than settled by whichever fallback was easiest.
+
+## Install
+
+Python 3.11 to 3.13.
+
+```bash
+pipx install mkctl
+mkctl --version
+```
+
+`mkp-contracts` comes with it from the same index. `mkctl upgrade` prints the upgrade
+command for whatever version the control plane currently declares.
+
+Before `0.4.0` there was no index, and those versions are still where they were — wheels
+attached to a `cli-v*` release of a **private** repository, so that path needs an account
+with access to it:
+
+```bash
+gh release download cli-v0.3.0 --repo gianlucamazza/mklang-platform -D /tmp/mkp-wheels
+pipx install /tmp/mkp-wheels/mkctl-*.whl --pip-args '--find-links /tmp/mkp-wheels'
+```
+
+`--repo` is not optional there: `gh release download` reads the repository from the
+current directory's git remote, so without it the command works only inside a checkout —
+the one place you do not need to install anything, because `./deploy/scripts/local mkctl …`
+already runs from there.
+
+## Configure
+
+One value: the control plane URL. `login` discovers the issuer and client id from
+`GET /v1/cli-config` and caches them in `~/.config/mkctl/config.toml` — a cache of
+what the platform declared, safe to delete, re-learned at the next login:
+
+```bash
+mkctl login --control-plane https://api.mklang.dev
+mkctl whoami
+```
+
+Flags beat environment variables (`MKCTL_*`), the environment beats the cached file,
+and the file beats asking again. Set `MKCTL_PROJECT` / `MKCTL_ENVIRONMENT` for the
+per-command defaults if you want them.
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run --with ruff ruff check .
+```
+
+The tests run against a conformant authorization server over real HTTP
+(`tests/authserver.py`) and a control plane over real HTTP (`tests/controlplane.py`) —
+not a mocked `httpx`. A mock would assert that we call the library the way we think we
+do, which is the belief under test, and the interesting failures here are protocol
+failures: a `slow_down` ignored, a `code_verifier` never sent, a rotated token not
+stored, a bearer that never reaches the request, an archive sent as a form field. Both
+fakes refuse what the real thing refuses — PKCE and single-use refresh on one side, a 401
+without a bearer and a 404 for an archive nobody registered on the other.
+
+The commands are driven through `main()` rather than called as functions, because the
+parser and the dispatch table are half of the feature: a command that works only from
+Python is the gap `C14` describes, one layer down.
+`test_every_command_the_parser_accepts_has_something_to_run` walks both and asserts it
+found something, which is `D6`'s lesson.
+
+Two things the tests here do not cover. A real browser and a real human: `mkctl login`
+against a running Zitadel is a manual check, and the discovery document that drives it was
+verified against one. And whether these commands drive the _real_ API — that is
+`tests/e2e`, where `test_the_cli_drives_the_platform_it_logs_into` pushes a signed bundle,
+deploys it, starts a run, and answers the escalation it parks on, against a real control
+plane with a real runner behind it.

mkctl-0.4.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "mkctl"
+version = "0.4.0"
+description = "The command line for the control plane (ADR 0004)"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.14"
+# `mkp-contracts` for one function: reading the manifest out of an archive
+# (`archive.manifest_of`). A CLI that unpacked a tar itself would be a second opinion
+# about what a bundle is, which is the thing that package exists to prevent.
+dependencies = ["httpx>=0.27", "keyring>=25.0", "mkp-contracts>=0.2.0"]
+
+[project.scripts]
+mkctl = "mkctl.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "types-PyYAML"]
+
+[tool.uv.sources]
+mkp-contracts = { path = "../../packages/mkp-contracts", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mkctl"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+# `S` reads production code. In a test the same rules are noise with a cost: a test that
+# asserts is doing its job (S101), a fixture's fake credential is a literal on purpose
+# (S105-S107), and a query built to set up a fixture is not a query an attacker reaches
+# (S608). Ignored by path rather than by line, because there would be one line per test.
+"tests/**" = ["S101", "S105", "S106", "S107", "S608"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+# Same settings as `mklang` and `packages/mkp-contracts` — see the note there on why
+# `warn_unused_ignores` is the one that earns its place first. Scope matches mklang too:
+# what ships. Extending it over the test suites is a separate, larger piece of work.
+files = ["src"]
+python_version = "3.11"
+check_untyped_defs = true
+disallow_incomplete_defs = true
+strict_equality = true
+no_implicit_reexport = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.pyright]
+typeCheckingMode = "basic"
+exclude = [".venv"]

mkctl-0.4.0/src/mkctl/__init__.py

@@ -0,0 +1,8 @@
+"""mkctl — the command line for the control plane.
+
+A human's terminal, which must not hold a password and must be revocable
+independently of the account (ADR 0004). It holds tokens the identity provider
+issued, in the OS keyring, and never a credential this platform minted.
+"""
+
+__version__ = "0.1.0"