aac-cli 0.1.5__tar.gz → 0.1.6__tar.gz

{aac_cli-0.1.5/aac_cli.egg-info → aac_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.1.5
+Version: 0.1.6
 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
@@ -56,8 +56,15 @@ Python 3.10 or newer is required.
 
 ## Guided setup for developer tenants: `aac init`
 
-`aac init` signs you in, registers a developer tenant (or reuses the one
-your profile is already bound to), takes the trust domain AAC assigns to the
+`aac init` prepares the AAC side of one of your agents on this machine: it
+registers the agent's identity with AAC and creates the keys, certificates
+and configuration its sidecar needs. The agent itself is yours. The first
+run also creates your profile and registers your tenant; run it again with
+a new `--workspace` and `--workload-path`, and the same `--trust-url` and
+`--idp`, for each further agent.
+
+Along the way it signs you in, registers a developer tenant (or reuses the
+one your profile is already bound to), takes the trust domain AAC assigns to the
 tenant, registers a sample workload, generates development keys and
 certificates, and writes a complete sidecar configuration together with the
 files the trust-anchor publisher and Docker Compose need.
@@ -86,6 +93,20 @@ aac init --profile stage \
   --create-tenant
 ```
 
+`--idp` names how you sign in: `github` or `google`, the two sign-ins AAC
+offers developer tenants. If you need another sign-in provider, contact
+support@cascadeauth.com.
+
+`--trust-url` is required when a workspace is created: it is the public URL
+where your AAC environment serves trust material, and for AAC stage it is
+`https://trust.stage.cascadeauth.dev`. If you leave it out, the command
+stops before creating anything and names the value your tenant already
+uses, if it has one.
+
+Setting up a new developer tenant takes two browser sign-ins: the first
+registers the tenant, the second starts the tenant-admin session that
+registers the workload. The command says so before the first one.
+
 Progress lines `[1/5]` to `[5/5]` name the five steps: tenant, sign-in,
 hosted trust domain, workload, and material; the configuration files are
 rendered last. Rerunning the
@@ -119,6 +140,101 @@ production means a tenant-admin key under production custody
 (`aac tenant rotate-admin-key`), a new root key id published by your
 publisher, and certificates from your approved issuer.
 
+### What a workspace is for, and how to use it
+
+A workspace holds everything one workload needs to run beside an AAC
+sidecar, kept apart from every other workload: its identity in your
+tenant's trust domain, its own root signing key and key id, its development
+CA and certificates, the pairing secret its sidecar and agent share, and the
+configuration files rendered for them. It also records how far setup got,
+so rerunning `aac init` resumes where it stopped.
+
+Use one workspace per workload. `aac init --workspace <name>` creates a
+workspace (with `--trust-url`) or resumes it (the default name is
+`starter`), and three commands look after it:
+
+```bash
+aac workspace status --workspace starter           # what exists, what is due, and the next step
+aac workspace renew --workspace starter            # fresh certificates and keys
+aac workspace render --workspace starter --force   # rewrite the configuration files
+```
+
+A second workload is a second workspace with its own workload path:
+
+```bash
+aac init --profile stage --workspace worker --workload-path demo/worker \
+  --idp github --trust-url https://trust.stage.cascadeauth.dev
+```
+
+Pass the same `--trust-url` and `--idp` as for your first workspace. Each
+workspace records its own, and the trust URL also goes into the tenant's
+`publisher.env`, which every workspace of the tenant shares. A render never
+changes that file's endpoints, so a workspace created with a different
+trust URL stops at its last step and has to be set up again under a new
+name.
+
+`--workspace` names the local files; `--workload-path` chooses the
+workload's identity, the path at the end of its SPIFFE ID (`demo/agent`
+unless you choose another). Two workspaces with the same workload path are
+the same workload holding different keys: that is what a replacement
+computer wants, and what a second workload does not. The workspace name is
+permanent, because the root key id is made from it. `aac init` needs the
+profile the workspace was created with; the `aac workspace` commands read it
+from the workspace itself.
+
+### What "render" means
+
+To render is to write the configuration files that follow from what the
+workspace records, without touching any key: `sidecar-config.yaml` and
+`compose.env` in the workspace, and `publisher.env` in the tenant
+directory. They hold endpoints, identifiers, settings and the paths of the
+key files, never key material.
+
+`aac init` renders them as its last step. Render again with
+`aac workspace render --workspace <name> --force` when a configuration file
+is lost or to change the layout; without `--force`, `render` refuses to
+overwrite files that exist. The layout decides the paths written into the
+sidecar configuration: `host` (the default) uses paths on this machine, for
+a sidecar that runs directly on it, and `container` uses the paths where the
+files are mounted inside the containers. `compose.env` always holds the
+paths on this machine that Docker mounts from, and `publisher.env` the
+paths a publisher running on this machine reads.
+
+`publisher.env` belongs to the tenant, and every workspace of the tenant
+renders it. A render rewrites its paths and poll interval for this machine
+(hand edits to those are replaced), but refuses, even with `--force`, to
+change its tenant ID, trust domain or URLs, because that would repoint the
+publisher for every workspace. The refusal names the values that differ.
+If the file is the stale one, for example after you deliberately moved the
+tenant to new endpoints and set up its workspaces again, move it aside
+(`mv publisher.env publisher.env.old` in the tenant directory) and render
+again from a workspace with the intended endpoints. The admin key and the
+published public keys stay where they are.
+
+### How profiles, workspaces and tenant data fit together
+
+```text
+profile (~/.aac/config) ── bound to ──> tenant
+                                          ├── credentials:      ~/.aac/credentials/<tenant-id>
+                                          ├── tenant directory: ~/.aac/tenants/<tenant-id>/
+                                          └── workspaces:       ~/.aac/workspaces/<name>/, one per workload
+```
+
+* A **profile**, in `~/.aac/config`, names the AAC admin and data-plane
+  endpoints you use and, once registration or sign-in has bound it, the one
+  tenant it acts for. The trust URL and the sign-in choice are recorded in
+  each workspace instead. "Profiles and configuration", further down,
+  covers profiles in full.
+* The **tenant data** is shared by all of a tenant's workspaces on this
+  machine: the tenant API key and the tenant-admin session in
+  `~/.aac/credentials/`, and the tenant directory
+  `~/.aac/tenants/<tenant-id>/` with the tenant-admin signing key, the public
+  keys and certificates the publisher uploads, and `publisher.env`.
+* A **workspace**, in `~/.aac/workspaces/<name>/`, holds one workload's
+  material. It records the profile and the tenant it was created for and
+  keeps them: one tenant can have many workspaces, and a workspace never
+  moves to another tenant.
+
 ### What each file is for, and what to back up
 
 The table lists every file the CLI creates, what it is for, how long it
@@ -126,21 +242,21 @@ lives and whether to back it up. `<workspace>` is the workspace name
 (default `starter`) and `<tenant-id>` the tenant id AAC allocated.
 
 <!-- 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 new-computer setup 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 |
+| No. | Material | Where | Used for | Lifetime | Back up? |
+|---|---|---|---|---|---|
+| 1 | 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` |
+| 2 | tenant_admin_session | `~/.aac/credentials/<tenant-id>.session` | CLI admin calls | hours; `aac sso login` | No. sign in again |
+| 3 | 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`; a lost public half is derived from the private key); production custody belongs in an HSM/KMS, not a password manager |
+| 4 | 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 the private key: a replacement workspace gets a new name and therefore a new key id, published alongside the old one until the old one is retired; its public copies are recreated from it |
+| 5 | 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; a lost copy of the certificate is copied back from `pki/dev-ca.crt` |
+| 6 | 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 |
+| 7 | 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 |
+| 8 | 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 |
+| 9 | 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 |
+| 10 | 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 |
+| 11 | 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 new-computer setup procedure) |
+| 12 | 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) |
+| 13 | 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 -->
 
 In short: back up the tenant API key and the whole tenant directory while
@@ -163,6 +279,17 @@ 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.
 
+`status` also names one next step, `next_command`. When material is
+missing, it is the fix for the first missing item: restore it from your
+backup, recreate a lost public copy from the file it copies, renew, or
+render. Otherwise it is renewal when a certificate is due. After the step,
+run `status` again. Commands it names that change your tenant carry the
+workspace's own `--tenant-id` and `--admin-url`, so a value left in
+`AAC_TENANT_ID` or `AAC_ADMIN_URL` cannot aim them at another tenant. The
+file recipes use `openssl`, which must be OpenSSL 1.1.1 or newer: the
+`openssl` that ships with macOS cannot read Ed25519 keys, so install a
+current OpenSSL there, for example with Homebrew.
+
 Every private file is created once, readable only by you, and never
 overwritten. Before generating anything, `init` checks every destination
 and refuses with the full list if one already exists. `aac init` never
@@ -173,6 +300,36 @@ side effect of setup. A second workspace for the same tenant
 (`--workspace other`) reuses the tenant-admin key and gets its own root key
 id.
 
+### What to do when keys and certificates expire
+
+It is the certificates that expire, and renewing replaces their keys with
+them. `aac workspace status` shows when each certificate runs out and flags
+it before it does: six hours ahead for the one-day certificates, a day
+ahead for the development CA.
+
+| Material | Lasts | When it runs out | What to do |
+|---|---|---|---|
+| Workload, terminal-attestation and localhost TLS certificates | 1 day | the sidecar can no longer prove its identity, sign receipts or serve HTTPS | `aac workspace renew --workspace <name>`, then restart the sidecar so it loads them |
+| Development CA | 7 days | certificates it signed stop being trusted, and no new ones can be issued | `renew` also replaces the CA when it is expired or within a day of expiry, or when `--ca` is given, and then reissues every certificate under it: restart the publisher so the new CA is published, restart the sidecar and anything else that trusted the old CA, and confirm with `aac workspace status --workspace <name> --remote` |
+| Tenant-admin session | hours | administration commands ask you to sign in again | `aac sso login` |
+| Tenant API key, tenant-admin signing key, root signing key | do not expire | — | replaced only on purpose: see "Keys" and "Setting up aac-cli on a new computer" |
+
+A simple routine: when you start work, run
+`aac workspace status --workspace <name>`, and when it names renewal, run
+`aac workspace renew --workspace <name>` and restart the sidecar. About once
+a week that renewal also replaces the development CA (`renew` then reports
+`republication_required: true`): restart the publisher, the sidecar and the
+agent, and anything else that trusted the old CA. Renewing is safe to
+repeat, but it is not a no-op: every run issues fresh keys and moves the old
+files to the workspace's `archive/` directory, so whatever reads them must
+reload. With the
+[AAC Compose starter](https://github.com/CascadeAuth/aac-compose-starter),
+`./starter up` recreates the containers so they load the new files; it
+does not renew anything itself.
+
+All of this is development material. In production, certificates come from
+your own issuer and follow its renewal process.
+
 ## Setting up aac-cli on a new computer
 
 This procedure covers a lost machine and a second machine alike. It needs
@@ -211,7 +368,8 @@ profile; `aac profile show` prints it, and the example below uses
    ```
 
    Restore `~/.aac/tenants/<tenant-id>/` from the backup, with directories
-   readable only by you and files likewise.
+   readable only by you and files likewise. Its `publisher.env` still names
+   the old machine's paths; step 3 rewrites them for this one.
 
    If the tenant directory was not backed up, first check whether another
    machine still holds `~/.aac/tenants/<tenant-id>/`: every machine that has
@@ -220,7 +378,8 @@ profile; `aac profile show` prints it, and the example below uses
 
    If no copy exists anywhere, the tenant-admin key and every root key that
    lived on the lost machine are gone for good. Install a new admin key,
-   then account for every root key the tenant has published:
+   then account for every root key the tenant has published (the `openssl`
+   commands need OpenSSL 1.1.1 or newer, which macOS does not ship):
 
    ```bash
    openssl genpkey -algorithm ed25519 -out tenant-admin.pem
@@ -359,13 +518,17 @@ aac sso whoami --profile stage --output table            # cached session and th
 aac sso logout --profile stage
 ```
 
+A developer tenant signs in with `--idp github` or `--idp google`; if you
+need another sign-in provider, contact support@cascadeauth.com. An
+enterprise tenant signs in through its Microsoft Entra ID connection, named
+by the connection's exact URL with `--idp-url`; when several connections
+are registered, the error message lists the exact commands to choose one.
+
 Sign-in uses the device flow by default, so the browser can be on another
 machine and headless hosts work. Google connections use a loopback flow
 instead, because Google's device flow is scope-restricted; `--flow`
-overrides the choice. An enterprise tenant names its identity-provider
-connection by the connection's exact URL with `--idp-url`; when several
-connections are registered, the error message lists the exact commands to
-choose one. `whoami` and `logout` work offline and never contact AAC.
+overrides the choice. `whoami` and `logout` work offline and never contact
+AAC.
 
 ## Output and exit codes
 
@@ -396,6 +559,10 @@ the `AAC_BOOTSTRAP_TOKEN` environment variable. The token authorises only
 the onboarding steps shown with it; every other administration command runs
 under a signed-in session.
 
+For enterprise sign-in, AAC supports Microsoft Entra ID (also known as
+Azure Active Directory or Azure AD). If your organisation needs another
+identity provider, contact support@cascadeauth.com.
+
 ### Register the tenant
 
 Generate the tenant-admin key pair first. The CLI transmits the public half
@@ -429,7 +596,8 @@ aac tenant update --profile prod --tenant-id tnt-550e8400-e29b-41d4-9716-4466554
 ### Connect your identity provider
 
 An identity-provider connection is described by a JSON file
-(`aac sso register-idp --help` shows the fields). Before the first
+(`aac sso register-idp --help` shows the fields, with an example for a
+Microsoft Entra ID tenant). Before the first
 connection, generate an offline recovery key so the connection can be
 repaired if the provider is ever unavailable; only the enrollment file
 leaves the machine:
@@ -468,6 +636,27 @@ aac tenant rotate-admin-key --profile prod \
   --tenant-admin-pubkey-file tenant-admin.public.pem
 ```
 
+A developer tenant set up with `aac init` keeps its tenant-admin key in its
+tenant directory, where the publisher's configuration points. To replace a
+lost key there, write the new pair in place, readable only by you, sign in,
+register the new public half, and then recreate every publisher container.
+Pass the tenant id and admin URL explicitly, as `aac workspace status`
+does, so the change cannot land on another tenant. The `openssl` commands
+need OpenSSL 1.1.1 or newer, which macOS does not ship:
+
+```bash
+cd ~/.aac/tenants/tnt-550e8400-e29b-41d4-9716-446655440000
+(umask 077 && openssl genpkey -algorithm ed25519 -out tenant-admin.pem.tmp && mv tenant-admin.pem.tmp tenant-admin.pem)
+(umask 077 && openssl pkey -in tenant-admin.pem -pubout -out tenant-admin.pub.pem.tmp && mv tenant-admin.pub.pem.tmp tenant-admin.pub.pem)
+aac sso login --profile stage --idp github \
+  --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000 \
+  --admin-url https://api.stage.cascadeauth.dev
+aac tenant rotate-admin-key --profile stage \
+  --tenant-id tnt-550e8400-e29b-41d4-9716-446655440000 \
+  --admin-url https://api.stage.cascadeauth.dev \
+  --tenant-admin-pubkey-file tenant-admin.pub.pem
+```
+
 The tenant API key can be rotated without downtime. `issue` stages a second
 active key in a new file and never replaces the current one; move every
 client to it, then retire the old key by its exact id: