aac-cli 0.2.9__tar.gz → 0.2.10__tar.gz

{aac_cli-0.2.9/aac_cli.egg-info → aac_cli-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.9
+Version: 0.2.10
 Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
 Author: Agent Authority Cloud Project
 License-Expression: Apache-2.0
@@ -741,6 +741,7 @@ aac profile show stage --output table             # stored and effective values,
 aac profile create prod --admin-url https://aac-admin.example.com \
   --data-plane-url https://aac-data.example.com
 aac profile update main                           # edit the built-in baseline
+aac profile update stage --unbind                 # clear the local tenant association
 aac profile delete prod                           # local only; never touches the server
 ```
 
@@ -757,6 +758,41 @@ stored value.
 for it; only `aac tenant register`, `aac init` and `aac sso login` write it.
 It is your organisation's identifier in the federation, allocated by AAC at
 registration in the form `tnt-<uuid>`, and it never changes.
+A binding makes that tenant the profile's stored default; it does not grant
+membership or configure an identity provider. Successful sign-in to an existing
+tenant binds the profile; registration binds a newly created tenant.
+
+A stale tenant binding affects only that profile. `aac profile list` and
+`aac profile show` mark invalid bindings without printing the invalid values;
+other profiles remain usable. Operational commands reject a selected invalid
+profile with exit 3, even if a tenant flag or environment override is supplied.
+File syntax, profile-name and size limits still apply to the entire file.
+
+Use `aac profile update NAME --unbind` to remove the local `tenant_id` and its
+saved hosted-domain metadata. Endpoints, other settings, credentials and the
+server-side tenant are preserved. The flag works without prompts, may accompany
+endpoint flags, and also works on `main` or an already-unbound profile. It
+refuses profiles with unresolved registration or API-key rotation state;
+finish that recovery first. Then bind the profile through registration or
+successful sign-in. Endpoint-only updates and confirmed profile deletion also
+work on stale profiles; reads never rewrite the config file.
+
+For an existing tenant, the repair sequence is:
+
+```bash
+aac profile update stage --unbind
+# Bind profile stage to the correct existing tenant:
+aac sso login --profile stage --tenant-id '<TENANT_ID>'
+```
+
+**`aac sso login --profile stage --tenant-id '<TENANT_ID>'` binds profile
+`stage` to that tenant.** Although the verb is `login`, successful authentication
+also saves the tenant association; there is no separate `--bind` flag. Replace
+`<TENANT_ID>` with the intended tenant's canonical ID. An endpoint correction
+or expired session normally does not need
+unbinding. Unbinding is local and does not log out, revoke access, or change
+existing agent records. See the [profile repair guide](https://docs.cascadeauth.com/cli/guide/#repair-a-stale-profile-binding)
+for the exact config fields removed and recovery constraints.
 
 `AAC_CLI_HOME` relocates the whole `~/.aac` tree. Use it for a throwaway
 test home, or to keep separate accounts hard-walled from each other:
@@ -774,13 +810,39 @@ Two credential files can coexist under `~/.aac/credentials/`:
   (`aac chain`, `aac trust-anchor`) present it. Only a hash of it exists
   on the server, so a lost key is replaced, never recovered.
 * `<tenant-id>.session` holds the short-lived session that `aac sso login`
-  creates. The administration commands (`aac tenant`, `aac sso`) use it
-  automatically. Sessions cannot be refreshed: when one expires, any
-  administration command tells you to sign in again, and there is no
-  refresh token that could be stolen.
+  creates. Authenticated administration commands use it automatically;
+  public reads such as `aac sso describe` do not use credentials.
+  Sessions have no refresh token. You can sign in again before expiry to
+  replace the cached session; after expiry, commands that need it ask you
+  to sign in again.
 
 ## Signing in
 
+Inspect the available sign-in connections before starting a login:
+
+```bash
+aac sso describe --profile stage                        # shared/platform candidates
+aac sso describe --profile stage --tenant-id '<TENANT_ID>' # tenant plus shared candidates
+```
+
+`sso describe` reads public metadata from the profile's admin endpoint and
+prints the complete descriptor as JSON on stdout. No credentials or prior
+sign-in are required, and it does not bind a profile or change cached credentials.
+The output includes `connections`, `count`, and, for the tenant route,
+`tenant_id`; connection fields describe issuers, client IDs and available flow
+endpoints. An empty connection list is a successful read.
+
+Only an explicit `--tenant-id` selects the tenant descriptor. Omitting it
+always reads shared/platform candidates, even when the profile or the
+`AAC_TENANT_ID` environment variable supplies a tenant. Replace `<TENANT_ID>`
+with the intended tenant's canonical ID. The CLI still checks your local
+configuration and selected profile. If it reports an invalid stored tenant
+binding, clear it with `aac profile update stage --unbind`, then retry.
+Output is JSON only (`--output json` is optional); errors go to stderr.
+See the [command reference](https://docs.cascadeauth.com/cli/reference/aac-sso-describe/).
+
+Then sign in using the connection you need:
+
 ```bash
 aac sso login --profile stage --idp github                # developer tenant: GitHub or Google
 aac sso login --profile prod \
@@ -798,6 +860,15 @@ enterprise tenant signs in through its Microsoft Entra ID connection, named
 by the connection's exact URL with `--idp-url`; when several connections
 are registered, the error message lists the exact commands to choose one.
 
+Sessions last **4 hours by default**. Your administrator may configure a
+different lifetime for the deployment or connection. You can run
+`aac sso login` again before expiry: successful authentication replaces the
+cached session with a new one whose lifetime starts at that login. For example,
+with the four-hour default, signing in at 09:00 gives an expiry of 13:00;
+signing in successfully again at 12:00 gives the new session an expiry of 16:00.
+Use `aac sso whoami --profile NAME --output table` to check the current
+expiration. If the session expires, sign in again; no refresh token is issued.
+
 Sign-in uses the device flow by default, so the browser can be on another
 machine and headless hosts work. Google connections use a loopback flow
 instead, because Google's device flow is scope-restricted; `--flow`
@@ -814,11 +885,16 @@ server-returned domain. Existing agents expose read-only identities through
 or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
 an unavailable value or unhealthy agent fails with empty stdout. `--field`
 cannot be combined with explicit `--output`, or with agent `--remote`.
+Scalar profile inspection rejects an invalid stored binding. Structured
+inspection remains available and reports invalid effective IDs as `null` with
+an `error`; invalid list bindings carry `binding_error`, and show bindings carry
+`binding.error`. Their invalid stored tenant IDs are redacted as `null`.
 
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
-so the JSON stays parseable in scripts; `--output table` prints a readable
-table instead. The three profile writers are the exception: `aac profile
+so the JSON stays parseable in scripts; where supported, `--output table`
+prints a readable table instead. `aac sso describe` supports JSON only.
+The three profile writers are the exception: `aac profile
 create`, `update` and `delete` confirm on standard error, leave standard
 output empty and take no `--output`.
 
@@ -829,6 +905,18 @@ output empty and take no `--output`.
 | `2` | Usage error: an invalid flag, value or flag combination. |
 | `3` | A local configuration or state problem: profile, credential file, cached session or agent. |
 | `4` | Transport failure: an endpoint could not be reached. |
+| `130` | Interrupted by the operator (Ctrl-C). |
+
+Ctrl-C stops `aac` and CLI-owned `aeg` without a traceback, with one concise
+diagnostic on standard error. A remote change may already have committed;
+follow any recovery guidance and retain pending registration or key-operation
+state. The CLI does not roll back or automatically retry a remote change.
+
+Walking away from sign-in retains the existing deadlines: device sign-in waits
+for the identity provider's device-code lifetime (300 seconds if absent), then
+exits `1` with instructions to run login again; a PKCE browser sign-in without
+a callback gives up after 300 seconds with exit `3`. HTTP timeouts remain exit
+`4`. These outcomes are distinct from Ctrl-C; there is no shorter patience cap.
 
 If AAC asks you to slow down, the command shows the interval to wait. The
 CLI never replays a change on its own; wait and rerun deliberately.

{aac_cli-0.2.9 → aac_cli-0.2.10}/README.md

@@ -714,6 +714,7 @@ aac profile show stage --output table             # stored and effective values,
 aac profile create prod --admin-url https://aac-admin.example.com \
   --data-plane-url https://aac-data.example.com
 aac profile update main                           # edit the built-in baseline
+aac profile update stage --unbind                 # clear the local tenant association
 aac profile delete prod                           # local only; never touches the server
 ```
 
@@ -730,6 +731,41 @@ stored value.
 for it; only `aac tenant register`, `aac init` and `aac sso login` write it.
 It is your organisation's identifier in the federation, allocated by AAC at
 registration in the form `tnt-<uuid>`, and it never changes.
+A binding makes that tenant the profile's stored default; it does not grant
+membership or configure an identity provider. Successful sign-in to an existing
+tenant binds the profile; registration binds a newly created tenant.
+
+A stale tenant binding affects only that profile. `aac profile list` and
+`aac profile show` mark invalid bindings without printing the invalid values;
+other profiles remain usable. Operational commands reject a selected invalid
+profile with exit 3, even if a tenant flag or environment override is supplied.
+File syntax, profile-name and size limits still apply to the entire file.
+
+Use `aac profile update NAME --unbind` to remove the local `tenant_id` and its
+saved hosted-domain metadata. Endpoints, other settings, credentials and the
+server-side tenant are preserved. The flag works without prompts, may accompany
+endpoint flags, and also works on `main` or an already-unbound profile. It
+refuses profiles with unresolved registration or API-key rotation state;
+finish that recovery first. Then bind the profile through registration or
+successful sign-in. Endpoint-only updates and confirmed profile deletion also
+work on stale profiles; reads never rewrite the config file.
+
+For an existing tenant, the repair sequence is:
+
+```bash
+aac profile update stage --unbind
+# Bind profile stage to the correct existing tenant:
+aac sso login --profile stage --tenant-id '<TENANT_ID>'
+```
+
+**`aac sso login --profile stage --tenant-id '<TENANT_ID>'` binds profile
+`stage` to that tenant.** Although the verb is `login`, successful authentication
+also saves the tenant association; there is no separate `--bind` flag. Replace
+`<TENANT_ID>` with the intended tenant's canonical ID. An endpoint correction
+or expired session normally does not need
+unbinding. Unbinding is local and does not log out, revoke access, or change
+existing agent records. See the [profile repair guide](https://docs.cascadeauth.com/cli/guide/#repair-a-stale-profile-binding)
+for the exact config fields removed and recovery constraints.
 
 `AAC_CLI_HOME` relocates the whole `~/.aac` tree. Use it for a throwaway
 test home, or to keep separate accounts hard-walled from each other:
@@ -747,13 +783,39 @@ Two credential files can coexist under `~/.aac/credentials/`:
   (`aac chain`, `aac trust-anchor`) present it. Only a hash of it exists
   on the server, so a lost key is replaced, never recovered.
 * `<tenant-id>.session` holds the short-lived session that `aac sso login`
-  creates. The administration commands (`aac tenant`, `aac sso`) use it
-  automatically. Sessions cannot be refreshed: when one expires, any
-  administration command tells you to sign in again, and there is no
-  refresh token that could be stolen.
+  creates. Authenticated administration commands use it automatically;
+  public reads such as `aac sso describe` do not use credentials.
+  Sessions have no refresh token. You can sign in again before expiry to
+  replace the cached session; after expiry, commands that need it ask you
+  to sign in again.
 
 ## Signing in
 
+Inspect the available sign-in connections before starting a login:
+
+```bash
+aac sso describe --profile stage                        # shared/platform candidates
+aac sso describe --profile stage --tenant-id '<TENANT_ID>' # tenant plus shared candidates
+```
+
+`sso describe` reads public metadata from the profile's admin endpoint and
+prints the complete descriptor as JSON on stdout. No credentials or prior
+sign-in are required, and it does not bind a profile or change cached credentials.
+The output includes `connections`, `count`, and, for the tenant route,
+`tenant_id`; connection fields describe issuers, client IDs and available flow
+endpoints. An empty connection list is a successful read.
+
+Only an explicit `--tenant-id` selects the tenant descriptor. Omitting it
+always reads shared/platform candidates, even when the profile or the
+`AAC_TENANT_ID` environment variable supplies a tenant. Replace `<TENANT_ID>`
+with the intended tenant's canonical ID. The CLI still checks your local
+configuration and selected profile. If it reports an invalid stored tenant
+binding, clear it with `aac profile update stage --unbind`, then retry.
+Output is JSON only (`--output json` is optional); errors go to stderr.
+See the [command reference](https://docs.cascadeauth.com/cli/reference/aac-sso-describe/).
+
+Then sign in using the connection you need:
+
 ```bash
 aac sso login --profile stage --idp github                # developer tenant: GitHub or Google
 aac sso login --profile prod \
@@ -771,6 +833,15 @@ enterprise tenant signs in through its Microsoft Entra ID connection, named
 by the connection's exact URL with `--idp-url`; when several connections
 are registered, the error message lists the exact commands to choose one.
 
+Sessions last **4 hours by default**. Your administrator may configure a
+different lifetime for the deployment or connection. You can run
+`aac sso login` again before expiry: successful authentication replaces the
+cached session with a new one whose lifetime starts at that login. For example,
+with the four-hour default, signing in at 09:00 gives an expiry of 13:00;
+signing in successfully again at 12:00 gives the new session an expiry of 16:00.
+Use `aac sso whoami --profile NAME --output table` to check the current
+expiration. If the session expires, sign in again; no refresh token is issued.
+
 Sign-in uses the device flow by default, so the browser can be on another
 machine and headless hosts work. Google connections use a loopback flow
 instead, because Google's device flow is scope-restricted; `--flow`
@@ -787,11 +858,16 @@ server-returned domain. Existing agents expose read-only identities through
 or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
 an unavailable value or unhealthy agent fails with empty stdout. `--field`
 cannot be combined with explicit `--output`, or with agent `--remote`.
+Scalar profile inspection rejects an invalid stored binding. Structured
+inspection remains available and reports invalid effective IDs as `null` with
+an `error`; invalid list bindings carry `binding_error`, and show bindings carry
+`binding.error`. Their invalid stored tenant IDs are redacted as `null`.
 
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
-so the JSON stays parseable in scripts; `--output table` prints a readable
-table instead. The three profile writers are the exception: `aac profile
+so the JSON stays parseable in scripts; where supported, `--output table`
+prints a readable table instead. `aac sso describe` supports JSON only.
+The three profile writers are the exception: `aac profile
 create`, `update` and `delete` confirm on standard error, leave standard
 output empty and take no `--output`.
 
@@ -802,6 +878,18 @@ output empty and take no `--output`.
 | `2` | Usage error: an invalid flag, value or flag combination. |
 | `3` | A local configuration or state problem: profile, credential file, cached session or agent. |
 | `4` | Transport failure: an endpoint could not be reached. |
+| `130` | Interrupted by the operator (Ctrl-C). |
+
+Ctrl-C stops `aac` and CLI-owned `aeg` without a traceback, with one concise
+diagnostic on standard error. A remote change may already have committed;
+follow any recovery guidance and retain pending registration or key-operation
+state. The CLI does not roll back or automatically retry a remote change.
+
+Walking away from sign-in retains the existing deadlines: device sign-in waits
+for the identity provider's device-code lifetime (300 seconds if absent), then
+exits `1` with instructions to run login again; a PKCE browser sign-in without
+a callback gives up after 300 seconds with exit `3`. HTTP timeouts remain exit
+`4`. These outcomes are distinct from Ctrl-C; there is no shorter patience cap.
 
 If AAC asks you to slow down, the command shows the interval to wait. The
 CLI never replays a change on its own; wait and rerun deliberately.

{aac_cli-0.2.9 → aac_cli-0.2.10}/aac_cli/__init__.py

@@ -10,4 +10,4 @@ entrypoint (`aac_cli.cli:entrypoint`).
 # test in bin/tests/test_cli_version_parity.py. A literal keeps the
 # shipped code free of import-time metadata lookups (and their
 # not-installed failure mode).
-__version__ = "0.2.9"
+__version__ = "0.2.10"

aac_cli-0.2.10/aac_cli/__main__.py

@@ -0,0 +1,13 @@
+"""`python -m aac_cli` — same entrypoint as the `aac` console script."""
+
+import sys
+
+try:
+    from aac_cli.cli import entrypoint
+
+    if __name__ == "__main__":
+        entrypoint()
+except KeyboardInterrupt:
+    # The shared command boundary is not loaded during early imports.
+    sys.stderr.write("aac: interrupted\n")
+    raise SystemExit(130) from None

{aac_cli-0.2.9 → aac_cli-0.2.10}/aac_cli/aeg_cli.py

@@ -7,6 +7,7 @@ import sys
 from importlib.resources import files
 
 from . import __version__
+from .interrupts import run_command
 
 
 def version_text() -> str:
@@ -15,6 +16,10 @@ def version_text() -> str:
 
 
 def main(argv: list[str] | None = None) -> int:
+    return run_command(lambda: _main(argv), prog="aeg")
+
+
+def _main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     if argv == ["--version"]:
         print(version_text())

{aac_cli-0.2.9 → aac_cli-0.2.10}/aac_cli/agent_cli.py

@@ -619,13 +619,21 @@ def cmd_agent_list(args: argparse.Namespace) -> int:
         row["certificates"] = case_for(record.material_source).name
         tenant = tenant_paths(record.tenant_id) if record.tenant_id else None
         health = assess(agent, tenant, record)
+        row["profile_binding_consistent"] = health.profile_binding_consistent
         row["next_command"] = next_step(agent, tenant, record, health)
         rows.append(row)
     if args.output == "table":
         if not rows:
             print(f"no agents under {directory}")
         for row in rows:
-            print(f"{row['agent']:<16}: {row.get('certificates', row.get('state', '-'))}")
+            binding_note = (
+                " (profile binding inconsistent)"
+                if row.get("profile_binding_consistent") is False
+                else ""
+            )
+            print(
+                f"{row['agent']:<16}: {row.get('certificates', row.get('state', '-'))}{binding_note}"
+            )
         return 0
     print(json.dumps({"agents": rows}, indent=2))
     return 0
@@ -708,7 +716,12 @@ def add_agent_parser(nouns: argparse._SubParsersAction) -> None:
     listing = verbs.add_parser(
         "list",
         help="List every agent under the CLI home with its tenant, case and state.",
-        description="List every agent; an unreadable or unsupported record is reported in that agent's state without hiding the other agents.",
+        description=(
+            "List every agent; an unreadable or unsupported record is reported in that "
+            "agent's state without hiding the other agents. Invalid profile bindings "
+            "are reported per agent: JSON includes profile_binding_consistent and the "
+            "repair next_command; table output marks inconsistent bindings."
+        ),
     )
     listing.add_argument(
         "--output", choices=("json", "table"), default="json", help="Output mode (JSON by default)."

{aac_cli-0.2.9 → aac_cli-0.2.10}/aac_cli/agent_health.py

@@ -22,7 +22,13 @@ from aac_cli.agent_layout import (
     material_inventory,
 )
 from aac_cli.agent_record import STEP_MATERIAL, AgentRecord
-from aac_cli.config import CliConfigError, cli_home, credentials_path, read_profile_section
+from aac_cli.config import (
+    CliConfigError,
+    cli_home,
+    credentials_path,
+    profile_binding_error,
+    read_profile_section,
+)
 from aac_cli.material_cases import MATERIAL_ISSUED_HERE, MATERIAL_SUPPLIED, ca_report_label
 from aac_cli.secure_files import managed_path_problem
 
@@ -40,6 +46,7 @@ class CertificateReport:
 class AgentHealth:
     setup_complete: bool
     profile_binding_consistent: bool
+    invalid_profile_binding: bool = False
     missing_files: list[str] = field(default_factory=list)
     permission_problems: list[str] = field(default_factory=list)
     certificates: dict[str, CertificateReport] = field(default_factory=dict)
@@ -74,7 +81,9 @@ class AgentHealth:
         reasons: list[str] = []
         if not self.setup_complete:
             reasons.append("setup is incomplete")
-        if not self.profile_binding_consistent:
+        if self.invalid_profile_binding:
+            reasons.append("the profile has an invalid stored tenant binding")
+        elif not self.profile_binding_consistent:
             reasons.append("the profile is bound to a different tenant than this agent")
         reasons.extend(f"missing: {name}" for name in self.missing_files)
         reasons.extend(self.permission_problems)
@@ -111,10 +120,16 @@ def _certificate_reports(
 
 def assess(agent: AgentPaths, tenant: TenantPaths | None, record: AgentRecord) -> AgentHealth:
     """The offline health assessment both `status` and a completed `init` report."""
-    profile_tenant = read_profile_section(record.profile).get("tenant_id")
+    # Offline inventory diagnoses this agent's profile without allowing one
+    # stale association to abort every other agent's inventory. Operational
+    # profile resolution stays strict; material paths use the validated record.
+    stored = read_profile_section(record.profile, validate_binding=False)
+    invalid_binding = profile_binding_error(stored) is not None
     health = AgentHealth(
         setup_complete=record.next_step() is None,
-        profile_binding_consistent=profile_tenant == record.tenant_id,
+        profile_binding_consistent=not invalid_binding
+        and stored.get("tenant_id") == record.tenant_id,
+        invalid_profile_binding=invalid_binding,
     )
     if tenant is None:
         return health
@@ -387,6 +402,8 @@ def next_step(
 ) -> str | None:
     """The one next step `status` reports and a refused `init` names; None when there is none."""
     agent_flag = f"--agent {_quote(agent.name)}"
+    if health.invalid_profile_binding:
+        return f"aac profile update {_quote(record.profile)} --unbind"
     if not health.setup_complete:
         return f"aac init --profile {_quote(record.profile)} {agent_flag}"
     if tenant is not None: