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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -8,6 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.28
+Requires-Dist: cryptography>=42.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-httpx>=0.30; extra == "test"
@@ -98,9 +99,51 @@ 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; 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
+# Publish the exact record printed above, then:
+aac tenant verify-domain --domain acme.example
+# B182 keeps verification and binding explicit. The binding command consumes
+# current exact-name evidence (and lazily revalidates when due); verify-domain
+# 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 --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"
+
+# If bind-trust-domain reports missing proof, its printed issue/verify/rerun
+# commands pin the selected profile, effective admin URL, tenant id, and exact
+# domain. They never print a session, bootstrap token, or challenge value.
+
+# B153 — replace the tenant-admin key. Accepts and transmits the PUBLIC half
+# ONLY. It never generates or writes private-key material, and it refuses a
+# private key without transmitting or logging it — it does read the file you
+# name, because refusing requires inspecting it.
+# Replacement is IMMEDIATE and forward-only: the previous key stops
+# verifying ingest JWSs at once (admin keys get NO grace window) and can
+# never be reinstated.
+openssl genpkey -algorithm ed25519 -out tenant-admin.pem
+openssl pkey -in tenant-admin.pem -pubout -out tenant-admin.public.pem
+aac tenant rotate-admin-key --tenant-admin-pubkey-file tenant-admin.public.pem
+# BEFORE running it in production: stage the new PRIVATE key on the
+# trust-anchor publisher host and be ready to restart it. The restart
+# procedure DIFFERS by deployment path — a Docker publisher's env and key
+# bind-mount are fixed at container creation, so a plain restart comes back
+# on the OLD key. Follow trust_anchor_publisher/INSTALL.md, "Rotating the
+# tenant-admin key". Publication stays paused until it restarts.
+# --bootstrap-token (or $AAC_BOOTSTRAP_TOKEN) lets a ceremony operator
+# rotate for a tenant that has no session.
+
 # B172 — post-registration workload lifecycle. --tenant-id is optional
 # here: the selected profile supplies it by default. JSON is default;
 # every command also supports --output table.
@@ -130,17 +173,90 @@ aac trust-anchor list --tenant-id tnt-<uuid>        # both roles, all states
 aac trust-anchor list --role tenant-admin           # ingest-signing keys only
 aac trust-anchor describe --kid key-1               # lifecycle + public PEM
 aac trust-anchor ingest-history --artifact-class root-keys --limit 20
+# Session-only emergency/environment-retirement operation. Terminal, may
+# revoke the last root, and cannot be authorized by bootstrap token/API key:
+aac trust-anchor revoke --tenant-id tnt-<uuid> --kid key-1 \
+    --reason "root signing key suspected compromised"
+
+# B144 — before the first tenant IdP, Tenant Ops generates an Ed25519
+# offline recovery keypair. The private PEM stays offline and mode 0600;
+# only the non-secret enrollment JSON crosses to AAC Ops/control plane.
+aac sso generate-idp-recovery-key \
+    --private-key-file offline-idp-recovery-private.pem \
+    --enrollment-file idp-recovery-enrollment.json
+aac sso enroll-idp-recovery-key \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --file idp-recovery-enrollment.json \
+    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
 
 # B140 — register a tenant↔IdP connection (Eng Spec §XVII.4; the sso
 # noun). The connection config rides as a JSON file (nested claims
-# mapping — see --help for an Entra example). First-IdP onboarding is
-# the ops ceremony; later IdPs ride your cached session instead:
+# mapping — see --help for an Entra example). Initial recovery-key
+# enrollment above happens before first-IdP registration. First-IdP
+# registration is the ops ceremony; later IdPs ride a cached session:
 # (--tenant-id takes the canonical tnt-<uuid> id captured at your
 # tenant's registration — B154 PR 5: a dotted value fails locally.)
 aac sso register-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
     --file connection.json \
     --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
 
+# B151 — discover the opaque connection id and current revision without a
+# session. The public response contains only safe issuer metadata, a stable
+# idp_connections.id, and the numeric ETag needed for correction:
+aac sso list-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
+
+# B151 — correct the COMPLETE connection document. Pin the revision you
+# reviewed; the CLI sends it with the cached tenant-admin session and never
+# substitutes a newer revision. Repeating after a lost response is safe:
+aac sso replace-idp --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --connection-id <id-from-list-idp> \
+    --revision <revision-from-list-idp> \
+    --file corrected-connection.json
+
+# B144 — if the IdP is unavailable, the same B151 replacement is authorized
+# by a three-command two-party ceremony. Tenant Ops signs the exact corrected
+# file and receives a request id plus REPAIR-INTENT fingerprint. AAC Ops
+# compares both through the incident channel, approves that exact intent, and
+# manually notifies Tenant Ops. Tenant Ops then runs replace-idp with the same
+# request/file/revision/key. The CLI internally redeems a ten-minute,
+# single-use capability, holds it only in memory, and never prints or stores it.
+# It grants no login, data-plane access, or general administration.
+aac sso request-idp-repair \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --connection-id <id-from-list-idp> \
+    --revision <revision-from-list-idp> \
+    --file corrected-connection.json \
+    --recovery-key-file offline-idp-recovery-private.pem
+aac sso approve-idp-repair \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --connection-id <id-from-list-idp> \
+    --repair-request-id <tenant-provided-request-id> \
+    --repair-intent-fingerprint sha256:<tenant-provided-intent-hash> \
+    --bootstrap-token "$AAC_BOOTSTRAP_TOKEN"
+aac sso replace-idp \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --connection-id <id-from-list-idp> \
+    --revision <same-request-revision> \
+    --file corrected-connection.json \
+    --repair-request-id <approved-request-id> \
+    --recovery-key-file offline-idp-recovery-private.pem
+
+# These fingerprints are different: recovery_key_fingerprint identifies the
+# enrolled Ed25519 PUBLIC key; repair_intent_fingerprint identifies one exact
+# tenant/connection/revision/document/key intent. Neither replaces the other.
+
+# Recovery-key lifecycle is normal-session administration. Generate a fresh
+# pair before rotation; old material cannot return. Revocation is terminal.
+aac sso list-idp-recovery-keys --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000
+aac sso rotate-idp-recovery-key \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --file new-idp-recovery-enrollment.json \
+    --replaces-recovery-key-id <current-active-key-id>
+aac sso revoke-idp-recovery-key \
+    --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+    --recovery-key-id <current-active-key-id> \
+    --reason "offline media lost"
+
 # B142 — register a SHARED developer-tier connection (platform
 # operator ceremony ONLY; owned by no tenant). GitHub registers with
 # jwks_static {"keys": []} + explicit endpoints (GitHub is not an OIDC
@@ -163,9 +279,9 @@ aac sso login --flow pkce --no-browser        # print the URL, don't launch
 # 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
 ```
 
@@ -248,6 +364,104 @@ one-time API key. The CLI binds the profile and transitions the state to
 `completed_credential_reissue_required`, directing the operator to the
 separate B173 reissue capability; B171 does not implement reissue.
 
+### Replace or recover a tenant API key (B173)
+
+After establishing an own-tenant `tenant-admin` session, run:
+
+```console
+aac tenant reissue-api-key \
+  --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+  --profile production
+```
+
+This is immediate replacement, not B98/B189 graceful rotation: the server
+revokes every ACTIVE tenant API key and returns one fresh `aac_ak_*` value once.
+The CLI makes one HTTP request per invocation and atomically replaces the
+mode-`0600` credential file only after validating the complete success
+response. A transport interruption leaves the local file untouched and tells
+the administrator to run the command again; the next explicit invocation is a
+fresh attempt that revokes any unknown prior result. There is no automatic
+retry or secret-response journal. A successful B173 replacement also removes
+any superseded non-secret B189 local rotation record. It does not silently
+delete the separate staged key file; that value is now revoked and must be
+removed through the approved secure-file procedure.
+
+After success the CLI prints copy/paste-ready `aac trust-anchor list` and curl
+commands for API-key-only verification against `GET /v1/trust-anchors`. The
+curl recipe streams the stored credential through stdin configuration rather
+than writing plaintext into shell history or an OS process argument.
+
+Operator-assisted onboarding recovery is exceptional and requires both the
+explicitly opened bootstrap ceremony and the matching completed registration
+locator. Load `AAC_BOOTSTRAP_TOKEN` through the approved secret-handling
+process, then run:
+
+```console
+aac tenant reissue-api-key \
+  --tenant-id tnt-550e8400-e29b-41d4-a716-446655440000 \
+  --registration-request-id treq-550e8400-e29b-41d4-a716-446655440000 \
+  --profile onboarding
+```
+
+The server admits this only before a tenant login path exists. The `treq-*`
+value is a locator, never a credential. Tenant API keys are separate from
+tenant-admin Ed25519 keys and B144 offline IdP-recovery material. See
+**SOP-010 — Recover or replace a tenant API key** in the AAC design vault's
+`sops/` directory for the tenant-administrator and AAC Ops procedures.
+
+### Rotate a tenant API key without downtime (B189)
+
+Planned rotation uses a nested command family and an own-tenant
+`tenant-admin` AAC session:
+
+```console
+aac tenant api-key list --profile production
+aac tenant api-key issue --profile production
+```
+
+`issue` saves a non-secret `akr-*` issuance identity before sending one HTTP
+request. It writes the returned plaintext only to a new mode-`0600` staged
+file (default `~/.aac/credentials/<tenant-id>.next`), refuses existing files
+and symlinks, requires any custom parent directory to exist, preserves that
+directory's permissions, and never replaces the current profile credential. Its success
+output contains metadata and a curl recipe that reads the staged file without
+putting plaintext in shell history or process arguments.
+
+Move every client to the staged key through the approved secret store, verify
+client traffic, then list again and select the old key by its exact non-secret
+`key_id`:
+
+```console
+aac tenant api-key retire \
+  --key-id ak_0123456789abcdef \
+  --yes \
+  --profile production
+```
+
+Retirement requires two ACTIVE keys and is terminal. The CLI fetches the
+authoritative set immediately before the request, names the exact key that will
+remain, and never guesses by age or position. It does not silently promote the
+staged file into the current credential location. Do that only through the
+approved local secret-handling procedure after the selected old key retires.
+
+If an issue response is ambiguous, rerun the same command. The saved identity
+is reused: a non-committed attempt may return the new plaintext, while a
+committed attempt reports that plaintext is unavailable and identifies the
+unknown new row through `api-key list`. Retire that unknown row, leaving the
+known old credential ACTIVE, then issue again. No automatic retry or plaintext
+journal exists. A profile with unresolved rotation state cannot be deleted.
+See **SOP-011 — Rotate a tenant API key without downtime** in the design vault.
+
+`~/.aac/idp-repair-requests/<tenant_id>/<connection_id>.json` is B144's
+separate AAC-managed IdP repair record (directory 0700, file 0600). It is
+written before `request-idp-repair` transmits anything and contains the exact
+connection document, document digest, request id, recovery-key fingerprint,
+and public signature. It contains neither the offline private key nor the
+short-lived AAC repair capability. An identical retry reuses the request id;
+a different live intent is refused locally. Preserve this file with the
+incident until replacement is complete, and do not edit, rename, copy between
+tenants, or delete it to “cancel” a request that may already exist server-side.
+
 ### `AAC_CLI_HOME` — isolated homes
 
 `AAC_CLI_HOME` relocates the whole `~/.aac` tree (config +
@@ -281,8 +495,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
 
@@ -298,9 +513,14 @@ captures it into the selected profile, and it is immutable, public,
 and never reused — like an AWS account ID. `--parent-tenant-id` takes
 the parent org's canonical `tnt-` id — the server resolves handles to
 internal row ids; no database identifier ever crosses the API (B118
-D3/D4). Domain ownership verification (DNS TXT) is a separate,
-additive control tracked in the `tenant_domains` table — the challenge
-flow ships in a follow-up increment.
+D3/D4). B121 domain ownership verification is a separate, additive
+control tracked in `tenant_domains`: `_aac-challenge.<domain>.` TXT
+`aac-verify=<token>`, issued/verified through the tenant-admin commands
+above. A verified business domain is evidence only. B182's separate
+`bind-trust-domain` request admits a domain's first SPIFFE binding only from
+B228-current evidence for the exact same name; parent-domain proof does not
+cover subdomains. SPIFFE-valid values outside the DNS proof grammar remain
+ceremony-only, and existing binding history remains B181.
 
 ## Semantics worth knowing
 
@@ -318,6 +538,9 @@ flow ships in a follow-up increment.
   configuration or state (missing profile/credential, malformed INI,
   bad registration state) / 4 transport failure (unreachable or timed
   out — the retryable class).
+* B159 rate limiting: a numeric server `Retry-After` is rendered beside
+  the stable 429/503 error. The CLI never automatically replays a
+  mutation; wait for the displayed interval and rerun deliberately.
 
 ## Tests
 
@@ -325,3 +548,39 @@ flow ships in a follow-up increment.
 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.
+
+## 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.