aac-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{aac_cli-0.1.2 → aac_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -9,6 +9,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.28
 Requires-Dist: cryptography>=42.0
+Requires-Dist: PyYAML>=6.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-httpx>=0.30; extra == "test"
@@ -99,14 +100,14 @@ aac sso login --profile dev            # thereafter: plain login
 # Tenant ids are the server-allocated canonical tnt-<uuid> form
 # (B154 PR 5) — captured at registration / shown by `aac profile show`.
 aac tenant list                                # which tenant ids exist (no 409 probe)
-aac tenant describe --tenant-id tnt-<uuid>     # workloads + key METADATA
+aac tenant describe --profile dev              # assigned domain, workloads + key METADATA
 aac tenant update --tenant-id tnt-<uuid> --display-name "ACME Manufacturing Inc"
 
 # B121/B228 — business-domain control proof and bounded claim lifecycle.
 # Registration can capture up to 16 pending rows with repeatable --tenant-domain.
 # The issue/verify/release/revoke commands
 # require the owning tenant's tenant-admin session and default --tenant-id from
-# the profile; the established tenant describe command keeps its explicit id.
+# the profile; tenant describe also uses the selected profile by default.
 aac tenant register --display-name "ACME" --contact ops@acme.example \
     --tenant-domain acme.example
 aac tenant issue-domain-challenge --domain acme.example
@@ -117,7 +118,7 @@ aac tenant verify-domain --domain acme.example
 # never performs an implicit binding write.
 aac tenant bind-trust-domain --trust-domain acme.example
 aac tenant list-trust-domains --output table
-aac tenant describe --tenant-id tnt-<uuid> --output table  # status + TXT
+aac tenant describe --profile dev --output table  # assigned binding status + TXT
 aac tenant release-domain --domain acme.example --reason "planned transfer"
 aac tenant revoke-domain --domain acme.example --reason "DNS control incident"
 
@@ -272,16 +273,17 @@ aac sso register-idp --shared --file shared-github.json \
 # admin verb (tenant list/describe/update, self-serve register-idp)
 # then rides the session automatically.
 aac sso login --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
-aac sso login --issuer https://login.microsoftonline.com/<tid>/v2.0  # >1 IdP
+aac sso login --idp github                    # developer tenant: GitHub or Google sign-in
+aac sso login --issuer https://login.microsoftonline.com/<tid>/v2.0  # enterprise IdP, by issuer URL
 aac sso login --flow pkce --no-browser        # print the URL, don't launch
 
 # Sessions are REFRESH-LESS by design (Eng Spec §XVII.2): on expiry
 # any admin verb tells you to re-run `aac sso login` — there is no
 # refresh token to steal, and no silent re-authentication.
 
-# B155 — session niceties (cache-file operations; the CLI never
-# parses the token itself). whoami exits 0 = live, 3 = expired/none (§14).
-aac sso whoami --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
+# B155/B239 — local session/profile inspection; no server call or JWT parsing.
+# whoami exits 0 = unexpired cache, 3 = expired/none (§14).
+aac sso whoami --profile dev --output table   # cached session + saved assigned domain
 aac sso logout --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
 ```
 
@@ -495,8 +497,9 @@ coexistence, Eng Spec §XVII.9):
   expiry fails fast locally with the re-login message instead of
   dialing out; the server's own session 401s carry the same
   remediation (the server stays authoritative). `aac sso logout`
-  removes the file; `aac sso whoami` reports its tenant + expiry
-  (B155 — both operate on the cache file only).
+  removes the file; `aac sso whoami` reports its tenant + expiry and, when
+  available, the matching profile's saved AAC-assigned domain. Both commands
+  operate locally; `whoami` does not verify current server-side binding status.
 
 ## Your tenant_id
 
@@ -547,3 +550,198 @@ ceremony-only, and existing binding history remains B181.
 needed. Against a live stack: bring up the joined topology
 (`./bin/run-wedge-a-control-plane-compose.sh --keep-up`) and point the
 flags at localhost.
+
+## Guided setup: `aac init` and `aac workspace`
+
+`aac init` takes a developer from an installed CLI to a complete, runnable
+local workload in one command. It signs you in, registers a developer tenant
+(or reuses the one your profile is already bound to), takes the AAC-assigned
+hosted trust domain, registers the sample workload, generates development
+keys and certificates, registers the tenant-admin public key together with a
+new tenant, and writes a complete sidecar configuration plus the publisher
+environment and a Compose variable file.
+
+```bash
+# Developer tier: sign in with GitHub or Google. The command shows what it
+# will create and asks before registering the tenant.
+aac init --profile stage --admin-url https://api.stage.cascadeauth.dev \
+  --data-plane-url https://api.stage.cascadeauth.dev \
+  --trust-url https://trust.stage.cascadeauth.dev \
+  --display-name 'YOUR TEAM' --contact 'YOUR EMAIL' --idp github
+
+# Scripted: every prompt has a flag; --create-tenant acknowledges creating a
+# permanent tenant when stdin is not a terminal.
+aac init --profile stage --admin-url ... --trust-url ... \
+  --display-name 'YOUR TEAM' --contact 'YOUR EMAIL' --idp github --create-tenant
+```
+
+Progress lines `[1/5]` to `[5/5]` name the five steps: tenant, sign-in, hosted trust
+domain, workload, material and rendering. A rerun prints every step, marking the ones
+already done. The sign-in you chose with `--idp` is remembered in the workspace, so a
+rerun (or `aac sso login --idp github` by hand when a session expires) never asks you
+to pick between GitHub and Google. Workspace commands take `--workspace <name>`; the
+profile is recorded in the workspace, so `--profile` is optional there and only checked.
+
+What it creates, and where:
+
+* `~/.aac/workspaces/<name>/` — the **workspace** for one workload (default
+  name `starter`): `pki/` with what the sidecar container mounts — the
+  workload, terminal-attestation and localhost TLS key pairs, this
+  workspace's root-signing key and the outbound CA bundle; `pair/` with what
+  both containers mount at `/run/secrets` — the pairing secret and the public
+  development CA certificate; `ca/` with the development CA private key (kept
+  out of both mounts so no container ever sees the key that mints
+  identities); `sidecar-config.yaml`; `compose.env` (non-secret variables for
+  a Compose consumer); and an internal manifest that lets a rerun resume.
+* `~/.aac/tenants/<tenant-id>/` — **tenant-level** material shared by every
+  workspace of that tenant: the tenant-admin signing key, the publisher's
+  input directories (`root-keys/`, `spiffe-bundle/` — public halves only) and
+  the rendered `publisher.env`.
+* The tenant API key stays where the CLI always kept it,
+  `~/.aac/credentials/<tenant-id>`; the rendered configuration references it
+  by path.
+
+### What each file is for, and what to back up
+
+The table below is rendered from the CLI's own layout module and checked by a test, so it
+cannot drift from the code. `<workspace>` is the workspace name (default `starter`) and
+`<tenant-id>` the server-allocated tenant id.
+
+<!-- inventory-table:start -->
+| Material | Where | Used for | Lifetime | Back up? |
+|---|---|---|---|---|
+| tenant_api_key | `~/.aac/credentials/<tenant-id>` | CLI data-plane calls; the sidecar's workload projection | until retired or rotated; `aac tenant reissue-api-key` | **Yes.** save a protected copy in your secret manager; loss needs `aac tenant reissue-api-key` |
+| tenant_admin_session | `~/.aac/credentials/<tenant-id>.session` | CLI admin calls | hours; `aac sso login` | No. sign in again |
+| tenant_admin_signing_key | `~/.aac/tenants/<tenant-id>/tenant-admin.pem`, `~/.aac/tenants/<tenant-id>/tenant-admin.pub.pem` | the publisher signs trust-material uploads; the public half is registered with AAC | until rotated; `aac tenant rotate-admin-key` | **Recommended.** recommended for developer tenants (loss needs `aac tenant rotate-admin-key`); production custody belongs in an HSM/KMS, not a password manager |
+| root_signing_key | `~/.aac/workspaces/<workspace>/pki/root.pem`, `~/.aac/workspaces/<workspace>/pki/root.pub.pem`, `~/.aac/tenants/<tenant-id>/root-keys/<workspace>-root-v1.pub.pem` | the sidecar mints authority chains; the public half is published under the key id | until you retire its key id (root key ids are fixed per workspace name) | No. never restore: a replacement workspace gets a new name and therefore a new key id, published alongside the old one until the old one is retired |
+| development_ca | `~/.aac/workspaces/<workspace>/ca/dev-ca.key`, `~/.aac/workspaces/<workspace>/pki/dev-ca.crt`, `~/.aac/workspaces/<workspace>/pair/dev-ca.crt`, `~/.aac/tenants/<tenant-id>/spiffe-bundle/<workspace>-dev-ca.ca.pem` | signs the workload, terminal and TLS certificates; peers trust it via the published bundle | 7 days; `aac workspace renew --ca` | No. development only; reissue |
+| workload_svid | `~/.aac/workspaces/<workspace>/pki/workload.key`, `~/.aac/workspaces/<workspace>/pki/workload.crt` | the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate | 1 day; `aac workspace renew` | No. development only; reissue |
+| terminal_attestation | `~/.aac/workspaces/<workspace>/pki/terminal.key`, `~/.aac/workspaces/<workspace>/pki/terminal.crt` | signs the receipt (terminal attestation) the sidecar issues when this workload completes a delegated request; auditors verify it offline against your published CA; kept separate from the workload key so neither can forge the other's role | 1 day; `aac workspace renew` | No. development only; reissue |
+| localhost_tls | `~/.aac/workspaces/<workspace>/pki/server.key`, `~/.aac/workspaces/<workspace>/pki/server.crt` | the sidecar's HTTPS listener | 1 day; `aac workspace renew` | No. development only; reissue |
+| outbound_ca_bundle | `~/.aac/workspaces/<workspace>/pki/outbound-ca.pem` | the sidecar verifies TLS to AAC and to itself | rebuilt by renew; `aac workspace renew` | No. derived |
+| pairing_secret | `~/.aac/workspaces/<workspace>/pair/pairing.secret` | the sidecar and its agent authenticate each other (same bytes in both) | until regenerated | No. regenerable; both processes must read the same file |
+| workspace_manifest | `~/.aac/workspaces/<workspace>/manifest.json` | the workspace's identities and progress; every `workspace` verb reads it first | for the life of the workspace | **Recommended.** cannot be recreated by any command; without it start a new workspace under a new name (see the machine-loss procedure) |
+| published_public_inputs | `~/.aac/tenants/<tenant-id>/root-keys`, `~/.aac/tenants/<tenant-id>/spiffe-bundle` | the publisher's input directories: every root public key and CA certificate this tenant has published, across all workspaces | for the life of the tenant | **Recommended.** back up with the tenant directory: a replacement workspace must publish its new root key alongside a still-ACTIVE previous one (the control plane refuses a root-key set that drops every ACTIVE key at once) |
+| rendered_files | `~/.aac/workspaces/<workspace>/sidecar-config.yaml`, `~/.aac/workspaces/<workspace>/compose.env`, `~/.aac/tenants/<tenant-id>/publisher.env` | non-secret configuration derived from the manifest | re-rendered on demand; `aac workspace render --force` | No. derived; `aac workspace render --force` recreates them |
+<!-- inventory-table:end -->
+
+#### If you lose this machine
+
+Back up two things while the machine is healthy: the tenant API key at
+`~/.aac/credentials/<tenant-id>`, and the whole tenant directory
+`~/.aac/tenants/<tenant-id>/` (the admin signing key plus the `root-keys/` and
+`spiffe-bundle/` public inputs the publisher has already published). The workspace
+manifest is worth keeping too, but a workspace can always be replaced. Then, on the new
+machine:
+
+1. Install the CLI and `aac profile create <name> --admin-url … --data-plane-url …`.
+   Sign in with `aac sso login --idp github --tenant-id <tenant-id> --profile <name>`
+   (or `--issuer <url>` for an enterprise connection): the remaining
+   steps register a workload and read the tenant's admin-key state, which need a
+   tenant-admin session whatever way the tenant was registered (a ceremony bootstrap
+   token only covers registration and hosted-domain assignment).
+2. Restore the tenant API key to `~/.aac/credentials/<tenant-id>` (mode `0600`), or issue a
+   new one with `aac tenant reissue-api-key` if it was not backed up. Restore
+   `~/.aac/tenants/<tenant-id>/` from the backup (directories `0700`, files `0600`).
+3. Run `aac init --profile <name> --workspace <new-name>` with a **new** workspace name.
+   Root key ids are fixed per workspace name and the control plane never accepts new key
+   material under an old id, so the replacement workspace publishes a new id
+   (`<new-name>-root-v1`) and a new development CA anchor.
+4. Start the publisher from the restored tenant directory. Its root-key set now holds the
+   old and the new public keys, which is what the control plane requires: a set that
+   drops every currently ACTIVE key at once is refused. Retire the old key later by
+   removing its public file once nothing signs with it.
+
+Reusing the old workspace name on the new machine is refused on purpose: the restored
+tenant directory still holds that name's published root key, and `init` never generates
+different key material under an existing key id. The development certificates and the
+pairing secret are regenerated by step 3; they are never restored.
+
+Every private file is created once at mode `0600` under `0700` directories
+and is never overwritten; before generating anything, `init` checks every
+destination and refuses with the full list if one already exists. Rerunning
+`aac init` resumes an interrupted setup (outcome `resumed`), reports a
+complete workspace (outcome `complete`, exit 0), or names the exact conflict
+(exit 3). Every post-registration step is pinned to the workspace's tenant,
+so a profile that has since been pointed at another tenant is refused rather
+than mixed in. A rerun on a complete workspace validates it offline (binding,
+files, permissions, certificate validity, CA fitness) and exits 3 with the
+next command if it is no longer usable. Missing flags for a new tenant are
+usage errors (exit 2).
+
+**`aac init` never installs or replaces a tenant-admin authority for an
+existing tenant.** For a new tenant it generates the admin key first and
+registers the public half together with the tenant, which the control plane
+creates in one transaction, so no competing authority can ever be retired by
+setup. For an existing tenant it only checks: the key on this machine must
+already be the tenant's ACTIVE admin key. If the tenant's ACTIVE key is not on
+this machine, `init` stops and tells you to restore that key to
+`~/.aac/tenants/<tenant-id>/tenant-admin.pem` (or pass
+`--tenant-admin-key-file`); if the tenant has no admin key at all, it tells
+you to install one deliberately with `aac tenant rotate-admin-key`. Replacing
+an authority is always that deliberate command, never a side effect of setup. Managed directories under `~/.aac/workspaces/` and
+`~/.aac/tenants/` must be real directories at mode `0700`; a symlink or a
+looser mode is refused before anything is written.
+A second workspace for the same tenant (`--workspace other`) reuses the
+tenant-admin key and gets its own root key id. Each key has an
+`--<role>-key-file` flag to use existing material instead of generating it.
+
+**Everything generated is development material.** The CA lives seven days and
+the leaf certificates one day; nothing here qualifies for production
+regardless of the tenant's hosted domain. Moving to production means
+`aac tenant rotate-admin-key` with a key under production custody, a new root
+key id published by your publisher, and certificates from your approved
+issuer.
+
+Inspect and maintain a workspace with the `workspace` noun:
+
+```bash
+aac workspace status --workspace starter            # what exists, expiry, permissions, next command
+aac workspace status --workspace starter --remote   # also: is the public trust material visible?
+aac workspace renew  --workspace starter            # fresh leaf keys + certificates; old ones archived
+aac workspace render --workspace starter --layout container --force   # container path layout
+```
+
+`status` is offline by default and exits 3 when material is missing, expired
+or unsafely permissioned. `renew` reissues the one-day certificates with fresh
+keys and reissues the development CA only when it is expired or within a day
+of expiry (or with `--ca`); a new CA is published under the next anchor id and
+needs the publisher restarted. `render` never touches keys and refuses to
+overwrite rendered files unless `--force` is given. Command, flag and path
+names are provisional until the public starter example has consumed them.
+
+## Assigned tenant domains (B239)
+
+Registration automatically saves the server-assigned `hosted_trust_domain` in
+the selected profile. The CLI displays the full name, explains its purpose in
+SPIFFE identities/certificates/trust configuration, and prints the command for
+finding it again. No manual copy is required. With JSON output, this guidance
+goes to stderr and stdout remains one JSON document; table output includes it
+inline. Completed-registration recovery provides the same saved-name guidance
+without changing credential-reissue requirements.
+
+```sh
+aac profile show dev --output table                         # saved locally, offline
+aac tenant describe --profile dev --output table            # assigned name + current binding status
+aac tenant list-trust-domains --profile dev --output table   # current ACTIVE bindings
+aac tenant list-trust-domains --profile dev --all --output table  # includes revoked history
+aac sso whoami --profile dev --output table                  # cached session + matching saved name
+```
+
+`tenant describe` accepts an optional `--tenant-id`; the usual flag → environment
+→ selected profile precedence applies. Its response comes from AAC. Binding
+table output labels AAC-assigned/custom origin, ACTIVE/REVOKED status and
+inherited scope. Registration, describe, profile show and binding-list JSON
+fields retain their existing shapes. `whoami` adds optional
+`hosted_trust_domain` and `hosted_trust_domain_source: "profile:<name>"` fields
+when that profile's saved tenant matches the inspected session. These fields
+describe locally saved metadata, not current binding eligibility. Tenant
+overrides never display another tenant's saved domain; session exit codes and
+offline operation are unchanged. Profile show says "not saved in this profile"
+when metadata is absent, without asserting that AAC has no allocation.
+
+Existing tenant admins use `aac tenant assign-hosted-domain --profile dev`;
+explicit eligible restoration uses `aac tenant reactivate-hosted-domain --profile dev`.
+Neither command registers another tenant or asks for a DNS name.
+See [the hosted-domain guide](../../docs/b239-hosted-trust-domains.md) for
+custom-domain progression, recovery compatibility and lifecycle limits.

{aac_cli-0.1.2 → aac_cli-0.1.4}/README.md

@@ -83,14 +83,14 @@ aac sso login --profile dev            # thereafter: plain login
 # Tenant ids are the server-allocated canonical tnt-<uuid> form
 # (B154 PR 5) — captured at registration / shown by `aac profile show`.
 aac tenant list                                # which tenant ids exist (no 409 probe)
-aac tenant describe --tenant-id tnt-<uuid>     # workloads + key METADATA
+aac tenant describe --profile dev              # assigned domain, workloads + key METADATA
 aac tenant update --tenant-id tnt-<uuid> --display-name "ACME Manufacturing Inc"
 
 # B121/B228 — business-domain control proof and bounded claim lifecycle.
 # Registration can capture up to 16 pending rows with repeatable --tenant-domain.
 # The issue/verify/release/revoke commands
 # require the owning tenant's tenant-admin session and default --tenant-id from
-# the profile; the established tenant describe command keeps its explicit id.
+# the profile; tenant describe also uses the selected profile by default.
 aac tenant register --display-name "ACME" --contact ops@acme.example \
     --tenant-domain acme.example
 aac tenant issue-domain-challenge --domain acme.example
@@ -101,7 +101,7 @@ aac tenant verify-domain --domain acme.example
 # never performs an implicit binding write.
 aac tenant bind-trust-domain --trust-domain acme.example
 aac tenant list-trust-domains --output table
-aac tenant describe --tenant-id tnt-<uuid> --output table  # status + TXT
+aac tenant describe --profile dev --output table  # assigned binding status + TXT
 aac tenant release-domain --domain acme.example --reason "planned transfer"
 aac tenant revoke-domain --domain acme.example --reason "DNS control incident"
 
@@ -256,16 +256,17 @@ aac sso register-idp --shared --file shared-github.json \
 # admin verb (tenant list/describe/update, self-serve register-idp)
 # then rides the session automatically.
 aac sso login --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
-aac sso login --issuer https://login.microsoftonline.com/<tid>/v2.0  # >1 IdP
+aac sso login --idp github                    # developer tenant: GitHub or Google sign-in
+aac sso login --issuer https://login.microsoftonline.com/<tid>/v2.0  # enterprise IdP, by issuer URL
 aac sso login --flow pkce --no-browser        # print the URL, don't launch
 
 # Sessions are REFRESH-LESS by design (Eng Spec §XVII.2): on expiry
 # any admin verb tells you to re-run `aac sso login` — there is no
 # refresh token to steal, and no silent re-authentication.
 
-# B155 — session niceties (cache-file operations; the CLI never
-# parses the token itself). whoami exits 0 = live, 3 = expired/none (§14).
-aac sso whoami --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
+# B155/B239 — local session/profile inspection; no server call or JWT parsing.
+# whoami exits 0 = unexpired cache, 3 = expired/none (§14).
+aac sso whoami --profile dev --output table   # cached session + saved assigned domain
 aac sso logout --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
 ```
 
@@ -479,8 +480,9 @@ coexistence, Eng Spec §XVII.9):
   expiry fails fast locally with the re-login message instead of
   dialing out; the server's own session 401s carry the same
   remediation (the server stays authoritative). `aac sso logout`
-  removes the file; `aac sso whoami` reports its tenant + expiry
-  (B155 — both operate on the cache file only).
+  removes the file; `aac sso whoami` reports its tenant + expiry and, when
+  available, the matching profile's saved AAC-assigned domain. Both commands
+  operate locally; `whoami` does not verify current server-side binding status.
 
 ## Your tenant_id
 
@@ -531,3 +533,198 @@ ceremony-only, and existing binding history remains B181.
 needed. Against a live stack: bring up the joined topology
 (`./bin/run-wedge-a-control-plane-compose.sh --keep-up`) and point the
 flags at localhost.
+
+## Guided setup: `aac init` and `aac workspace`
+
+`aac init` takes a developer from an installed CLI to a complete, runnable
+local workload in one command. It signs you in, registers a developer tenant
+(or reuses the one your profile is already bound to), takes the AAC-assigned
+hosted trust domain, registers the sample workload, generates development
+keys and certificates, registers the tenant-admin public key together with a
+new tenant, and writes a complete sidecar configuration plus the publisher
+environment and a Compose variable file.
+
+```bash
+# Developer tier: sign in with GitHub or Google. The command shows what it
+# will create and asks before registering the tenant.
+aac init --profile stage --admin-url https://api.stage.cascadeauth.dev \
+  --data-plane-url https://api.stage.cascadeauth.dev \
+  --trust-url https://trust.stage.cascadeauth.dev \
+  --display-name 'YOUR TEAM' --contact 'YOUR EMAIL' --idp github
+
+# Scripted: every prompt has a flag; --create-tenant acknowledges creating a
+# permanent tenant when stdin is not a terminal.
+aac init --profile stage --admin-url ... --trust-url ... \
+  --display-name 'YOUR TEAM' --contact 'YOUR EMAIL' --idp github --create-tenant
+```
+
+Progress lines `[1/5]` to `[5/5]` name the five steps: tenant, sign-in, hosted trust
+domain, workload, material and rendering. A rerun prints every step, marking the ones
+already done. The sign-in you chose with `--idp` is remembered in the workspace, so a
+rerun (or `aac sso login --idp github` by hand when a session expires) never asks you
+to pick between GitHub and Google. Workspace commands take `--workspace <name>`; the
+profile is recorded in the workspace, so `--profile` is optional there and only checked.
+
+What it creates, and where:
+
+* `~/.aac/workspaces/<name>/` — the **workspace** for one workload (default
+  name `starter`): `pki/` with what the sidecar container mounts — the
+  workload, terminal-attestation and localhost TLS key pairs, this
+  workspace's root-signing key and the outbound CA bundle; `pair/` with what
+  both containers mount at `/run/secrets` — the pairing secret and the public
+  development CA certificate; `ca/` with the development CA private key (kept
+  out of both mounts so no container ever sees the key that mints
+  identities); `sidecar-config.yaml`; `compose.env` (non-secret variables for
+  a Compose consumer); and an internal manifest that lets a rerun resume.
+* `~/.aac/tenants/<tenant-id>/` — **tenant-level** material shared by every
+  workspace of that tenant: the tenant-admin signing key, the publisher's
+  input directories (`root-keys/`, `spiffe-bundle/` — public halves only) and
+  the rendered `publisher.env`.
+* The tenant API key stays where the CLI always kept it,
+  `~/.aac/credentials/<tenant-id>`; the rendered configuration references it
+  by path.
+
+### What each file is for, and what to back up
+
+The table below is rendered from the CLI's own layout module and checked by a test, so it
+cannot drift from the code. `<workspace>` is the workspace name (default `starter`) and
+`<tenant-id>` the server-allocated tenant id.
+
+<!-- inventory-table:start -->
+| Material | Where | Used for | Lifetime | Back up? |
+|---|---|---|---|---|
+| tenant_api_key | `~/.aac/credentials/<tenant-id>` | CLI data-plane calls; the sidecar's workload projection | until retired or rotated; `aac tenant reissue-api-key` | **Yes.** save a protected copy in your secret manager; loss needs `aac tenant reissue-api-key` |
+| tenant_admin_session | `~/.aac/credentials/<tenant-id>.session` | CLI admin calls | hours; `aac sso login` | No. sign in again |
+| tenant_admin_signing_key | `~/.aac/tenants/<tenant-id>/tenant-admin.pem`, `~/.aac/tenants/<tenant-id>/tenant-admin.pub.pem` | the publisher signs trust-material uploads; the public half is registered with AAC | until rotated; `aac tenant rotate-admin-key` | **Recommended.** recommended for developer tenants (loss needs `aac tenant rotate-admin-key`); production custody belongs in an HSM/KMS, not a password manager |
+| root_signing_key | `~/.aac/workspaces/<workspace>/pki/root.pem`, `~/.aac/workspaces/<workspace>/pki/root.pub.pem`, `~/.aac/tenants/<tenant-id>/root-keys/<workspace>-root-v1.pub.pem` | the sidecar mints authority chains; the public half is published under the key id | until you retire its key id (root key ids are fixed per workspace name) | No. never restore: a replacement workspace gets a new name and therefore a new key id, published alongside the old one until the old one is retired |
+| development_ca | `~/.aac/workspaces/<workspace>/ca/dev-ca.key`, `~/.aac/workspaces/<workspace>/pki/dev-ca.crt`, `~/.aac/workspaces/<workspace>/pair/dev-ca.crt`, `~/.aac/tenants/<tenant-id>/spiffe-bundle/<workspace>-dev-ca.ca.pem` | signs the workload, terminal and TLS certificates; peers trust it via the published bundle | 7 days; `aac workspace renew --ca` | No. development only; reissue |
+| workload_svid | `~/.aac/workspaces/<workspace>/pki/workload.key`, `~/.aac/workspaces/<workspace>/pki/workload.crt` | the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate | 1 day; `aac workspace renew` | No. development only; reissue |
+| terminal_attestation | `~/.aac/workspaces/<workspace>/pki/terminal.key`, `~/.aac/workspaces/<workspace>/pki/terminal.crt` | signs the receipt (terminal attestation) the sidecar issues when this workload completes a delegated request; auditors verify it offline against your published CA; kept separate from the workload key so neither can forge the other's role | 1 day; `aac workspace renew` | No. development only; reissue |
+| localhost_tls | `~/.aac/workspaces/<workspace>/pki/server.key`, `~/.aac/workspaces/<workspace>/pki/server.crt` | the sidecar's HTTPS listener | 1 day; `aac workspace renew` | No. development only; reissue |
+| outbound_ca_bundle | `~/.aac/workspaces/<workspace>/pki/outbound-ca.pem` | the sidecar verifies TLS to AAC and to itself | rebuilt by renew; `aac workspace renew` | No. derived |
+| pairing_secret | `~/.aac/workspaces/<workspace>/pair/pairing.secret` | the sidecar and its agent authenticate each other (same bytes in both) | until regenerated | No. regenerable; both processes must read the same file |
+| workspace_manifest | `~/.aac/workspaces/<workspace>/manifest.json` | the workspace's identities and progress; every `workspace` verb reads it first | for the life of the workspace | **Recommended.** cannot be recreated by any command; without it start a new workspace under a new name (see the machine-loss procedure) |
+| published_public_inputs | `~/.aac/tenants/<tenant-id>/root-keys`, `~/.aac/tenants/<tenant-id>/spiffe-bundle` | the publisher's input directories: every root public key and CA certificate this tenant has published, across all workspaces | for the life of the tenant | **Recommended.** back up with the tenant directory: a replacement workspace must publish its new root key alongside a still-ACTIVE previous one (the control plane refuses a root-key set that drops every ACTIVE key at once) |
+| rendered_files | `~/.aac/workspaces/<workspace>/sidecar-config.yaml`, `~/.aac/workspaces/<workspace>/compose.env`, `~/.aac/tenants/<tenant-id>/publisher.env` | non-secret configuration derived from the manifest | re-rendered on demand; `aac workspace render --force` | No. derived; `aac workspace render --force` recreates them |
+<!-- inventory-table:end -->
+
+#### If you lose this machine
+
+Back up two things while the machine is healthy: the tenant API key at
+`~/.aac/credentials/<tenant-id>`, and the whole tenant directory
+`~/.aac/tenants/<tenant-id>/` (the admin signing key plus the `root-keys/` and
+`spiffe-bundle/` public inputs the publisher has already published). The workspace
+manifest is worth keeping too, but a workspace can always be replaced. Then, on the new
+machine:
+
+1. Install the CLI and `aac profile create <name> --admin-url … --data-plane-url …`.
+   Sign in with `aac sso login --idp github --tenant-id <tenant-id> --profile <name>`
+   (or `--issuer <url>` for an enterprise connection): the remaining
+   steps register a workload and read the tenant's admin-key state, which need a
+   tenant-admin session whatever way the tenant was registered (a ceremony bootstrap
+   token only covers registration and hosted-domain assignment).
+2. Restore the tenant API key to `~/.aac/credentials/<tenant-id>` (mode `0600`), or issue a
+   new one with `aac tenant reissue-api-key` if it was not backed up. Restore
+   `~/.aac/tenants/<tenant-id>/` from the backup (directories `0700`, files `0600`).
+3. Run `aac init --profile <name> --workspace <new-name>` with a **new** workspace name.
+   Root key ids are fixed per workspace name and the control plane never accepts new key
+   material under an old id, so the replacement workspace publishes a new id
+   (`<new-name>-root-v1`) and a new development CA anchor.
+4. Start the publisher from the restored tenant directory. Its root-key set now holds the
+   old and the new public keys, which is what the control plane requires: a set that
+   drops every currently ACTIVE key at once is refused. Retire the old key later by
+   removing its public file once nothing signs with it.
+
+Reusing the old workspace name on the new machine is refused on purpose: the restored
+tenant directory still holds that name's published root key, and `init` never generates
+different key material under an existing key id. The development certificates and the
+pairing secret are regenerated by step 3; they are never restored.
+
+Every private file is created once at mode `0600` under `0700` directories
+and is never overwritten; before generating anything, `init` checks every
+destination and refuses with the full list if one already exists. Rerunning
+`aac init` resumes an interrupted setup (outcome `resumed`), reports a
+complete workspace (outcome `complete`, exit 0), or names the exact conflict
+(exit 3). Every post-registration step is pinned to the workspace's tenant,
+so a profile that has since been pointed at another tenant is refused rather
+than mixed in. A rerun on a complete workspace validates it offline (binding,
+files, permissions, certificate validity, CA fitness) and exits 3 with the
+next command if it is no longer usable. Missing flags for a new tenant are
+usage errors (exit 2).
+
+**`aac init` never installs or replaces a tenant-admin authority for an
+existing tenant.** For a new tenant it generates the admin key first and
+registers the public half together with the tenant, which the control plane
+creates in one transaction, so no competing authority can ever be retired by
+setup. For an existing tenant it only checks: the key on this machine must
+already be the tenant's ACTIVE admin key. If the tenant's ACTIVE key is not on
+this machine, `init` stops and tells you to restore that key to
+`~/.aac/tenants/<tenant-id>/tenant-admin.pem` (or pass
+`--tenant-admin-key-file`); if the tenant has no admin key at all, it tells
+you to install one deliberately with `aac tenant rotate-admin-key`. Replacing
+an authority is always that deliberate command, never a side effect of setup. Managed directories under `~/.aac/workspaces/` and
+`~/.aac/tenants/` must be real directories at mode `0700`; a symlink or a
+looser mode is refused before anything is written.
+A second workspace for the same tenant (`--workspace other`) reuses the
+tenant-admin key and gets its own root key id. Each key has an
+`--<role>-key-file` flag to use existing material instead of generating it.
+
+**Everything generated is development material.** The CA lives seven days and
+the leaf certificates one day; nothing here qualifies for production
+regardless of the tenant's hosted domain. Moving to production means
+`aac tenant rotate-admin-key` with a key under production custody, a new root
+key id published by your publisher, and certificates from your approved
+issuer.
+
+Inspect and maintain a workspace with the `workspace` noun:
+
+```bash
+aac workspace status --workspace starter            # what exists, expiry, permissions, next command
+aac workspace status --workspace starter --remote   # also: is the public trust material visible?
+aac workspace renew  --workspace starter            # fresh leaf keys + certificates; old ones archived
+aac workspace render --workspace starter --layout container --force   # container path layout
+```
+
+`status` is offline by default and exits 3 when material is missing, expired
+or unsafely permissioned. `renew` reissues the one-day certificates with fresh
+keys and reissues the development CA only when it is expired or within a day
+of expiry (or with `--ca`); a new CA is published under the next anchor id and
+needs the publisher restarted. `render` never touches keys and refuses to
+overwrite rendered files unless `--force` is given. Command, flag and path
+names are provisional until the public starter example has consumed them.
+
+## Assigned tenant domains (B239)
+
+Registration automatically saves the server-assigned `hosted_trust_domain` in
+the selected profile. The CLI displays the full name, explains its purpose in
+SPIFFE identities/certificates/trust configuration, and prints the command for
+finding it again. No manual copy is required. With JSON output, this guidance
+goes to stderr and stdout remains one JSON document; table output includes it
+inline. Completed-registration recovery provides the same saved-name guidance
+without changing credential-reissue requirements.
+
+```sh
+aac profile show dev --output table                         # saved locally, offline
+aac tenant describe --profile dev --output table            # assigned name + current binding status
+aac tenant list-trust-domains --profile dev --output table   # current ACTIVE bindings
+aac tenant list-trust-domains --profile dev --all --output table  # includes revoked history
+aac sso whoami --profile dev --output table                  # cached session + matching saved name
+```
+
+`tenant describe` accepts an optional `--tenant-id`; the usual flag → environment
+→ selected profile precedence applies. Its response comes from AAC. Binding
+table output labels AAC-assigned/custom origin, ACTIVE/REVOKED status and
+inherited scope. Registration, describe, profile show and binding-list JSON
+fields retain their existing shapes. `whoami` adds optional
+`hosted_trust_domain` and `hosted_trust_domain_source: "profile:<name>"` fields
+when that profile's saved tenant matches the inspected session. These fields
+describe locally saved metadata, not current binding eligibility. Tenant
+overrides never display another tenant's saved domain; session exit codes and
+offline operation are unchanged. Profile show says "not saved in this profile"
+when metadata is absent, without asserting that AAC has no allocation.
+
+Existing tenant admins use `aac tenant assign-hosted-domain --profile dev`;
+explicit eligible restoration uses `aac tenant reactivate-hosted-domain --profile dev`.
+Neither command registers another tenant or asks for a DNS name.
+See [the hosted-domain guide](../../docs/b239-hosted-trust-domains.md) for
+custom-domain progression, recovery compatibility and lifecycle limits.

{aac_cli-0.1.2 → aac_cli-0.1.4}/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.1.2"
+__version__ = "0.1.4"