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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.1.3
+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"
@@ -272,7 +273,8 @@ 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
@@ -549,6 +551,165 @@ 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

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

@@ -256,7 +256,8 @@ 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
@@ -533,6 +534,165 @@ 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

{aac_cli-0.1.3 → 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.3"
+__version__ = "0.1.4"

{aac_cli-0.1.3 → aac_cli-0.1.4}/aac_cli/cli.py

@@ -125,6 +125,7 @@ from aac_cli.idp_recovery import (
 from aac_cli.idp_recovery import (
     encode_signature as encode_idp_recovery_signature,
 )
+from aac_cli.init_cli import add_init_parser
 from aac_cli.profiles import (
     cmd_profile_create,
     cmd_profile_delete,
@@ -159,6 +160,7 @@ from aac_cli.sso_login import (
     select_connection,
     select_flow,
 )
+from aac_cli.workspace_cli import add_workspace_parser
 
 __all__ = ["build_parser", "entrypoint", "main"]
 
@@ -438,8 +440,8 @@ def _print_api_key_verification_guidance(
         "    curl --fail-with-body --silent --show-error --config - \\\n"
         f"      {shlex.quote(verification_url)}\n\n"
         "A 200 response confirms the new key. Do not place the plaintext "
-        "key directly in a shell command. The key is stored at the printed "
-        "path; transfer it from that file to the organization's approved "
+        f"key directly in a shell command. The key is stored at {credential_path}; "
+        "transfer it from that file to the organization's approved "
         "secret store for any other system, never through chat, tickets, or "
         "shell arguments.",
         file=sys.stderr,
@@ -941,7 +943,8 @@ def _cmd_tenant_register_locked(args: argparse.Namespace, profile: str) -> int:
             return 3
         if recovered_domain is not None:
             payload["hosted_trust_domain"] = recovered_domain
-            _print_hosted_domain_guidance(recovered_domain, profile, output=args.output)
+            if not getattr(args, "guided", False):
+                _print_hosted_domain_guidance(recovered_domain, profile, output=args.output)
         try:
             read_api_key(returned_tenant_id)
         except CliConfigError:
@@ -1079,16 +1082,19 @@ def _cmd_tenant_register_locked(args: argparse.Namespace, profile: str) -> int:
             print(
                 f"\nNEXT: your {intent.admission.idp} identity is this "
                 f"tenant's first tenant-admin — sign in with:\n"
-                f"  aac sso login --tenant-id {returned_tenant_id} "
-                f"--profile {profile}"
+                f"  aac sso login --idp {intent.admission.idp} "
+                f"--tenant-id {returned_tenant_id} --profile {shlex.quote(profile)}"
             )
     else:
         print(json.dumps(result, indent=2))
-    if payload.get("hosted_trust_domain") is not None:
+    # `aac init` drives this verb and prints its own step summary: the
+    # human guidance below would interleave with the guided progress.
+    guided = bool(getattr(args, "guided", False))
+    if payload.get("hosted_trust_domain") is not None and not guided:
         _print_hosted_domain_guidance(
             payload["hosted_trust_domain"]["trust_domain"], profile, output=args.output
         )
-    if stored_at is not None:
+    if stored_at is not None and not guided:
         _print_api_key_verification_guidance(
             tenant_id=returned_tenant_id,
             profile=profile,
@@ -4102,6 +4108,19 @@ def _default_scope_for(connection: LoginConnection) -> str:
     return "openid profile email"
 
 
+def _login_command_prefix(args: argparse.Namespace, tenant_id: str) -> str:
+    """`aac sso login …` as the caller invoked it, so printed remedies run unchanged."""
+    prefix = (
+        f"aac sso login --tenant-id {tenant_id} "
+        f"--profile {shlex.quote(select_profile(args.profile).name)}"
+    )
+    if args.admin_url:
+        prefix += f" --admin-url {shlex.quote(args.admin_url)}"
+    if args.data_plane_url:
+        prefix += f" --data-plane-url {shlex.quote(args.data_plane_url)}"
+    return prefix
+
+
 def _cmd_sso_login(args: argparse.Namespace) -> int:
     """B141 (§XVII.9): the aws-sso-login UX for AAC.
 
@@ -4153,7 +4172,12 @@ def _cmd_sso_login(args: argparse.Namespace) -> int:
         print(line, file=sys.stderr)
 
     try:
-        connection = select_connection(connections, args.issuer)
+        connection = select_connection(
+            connections,
+            args.issuer,
+            args.idp,
+            command_prefix=_login_command_prefix(args, tenant_id),
+        )
         flow = select_flow(connection, args.flow)
         scope = args.scope if args.scope is not None else _default_scope_for(connection)
         evidence_token = _run_login_flow(
@@ -4237,6 +4261,11 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--version", action="version", version=f"aac {__version__}")
     nouns = parser.add_subparsers(dest="noun", required=True)
 
+    # `aac init` is a meta command beside `doctor`/`version`; `workspace` is the
+    # noun for what it creates (CLI Config+Profile Spec, B241 amendment §C/§D).
+    add_init_parser(nouns)
+    add_workspace_parser(nouns)
+
     profile = nouns.add_parser(
         "profile",
         help="Manage local profiles (list/show/create/update/delete).",
@@ -4484,6 +4513,7 @@ def build_parser() -> argparse.ArgumentParser:
             "federated evidence instead)."
         ),
     )
+    register.add_argument("--guided", action="store_true", help=argparse.SUPPRESS)
     register.add_argument(
         "--idp",
         choices=("github", "google"),
@@ -5527,10 +5557,20 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Tenant to sign in TO (default: profile/env tenant).",
     )
-    login.add_argument(
+    which = login.add_mutually_exclusive_group()
+    which.add_argument(
         "--issuer",
         default=None,
-        help="Which IdP connection to use (required when several are registered).",
+        help=(
+            "Which IdP connection to use, by its full issuer URL (needed when several "
+            "are registered; the error lists the exact commands)."
+        ),
+    )
+    which.add_argument(
+        "--idp",
+        choices=("github", "google"),
+        default=None,
+        help="Short form of --issuer for the shared developer sign-ins: github or google.",
     )
     login.add_argument(
         "--flow",