indraq_cli 2.1.0 → 2.2.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 IndraQ Innovations
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 IndraQ Innovations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
 
   **One CLI for provider access, project infrastructure and deployments.**
 
-  ![version](https://img.shields.io/badge/version-2.1.0-blue)
+  ![version](https://img.shields.io/badge/version-2.2.0-blue)
   ![node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
   ![typescript](https://img.shields.io/badge/TypeScript-5.x-blue)
   ![license](https://img.shields.io/badge/license-MIT-lightgrey)
@@ -19,7 +19,7 @@
 
 IndraQ is an internal engineering CLI that connects your team to shared infrastructure without making every developer carry organization administrator credentials.
 
-Instead of configuring “one AWS”, “one Jenkins”, or “one NPM” globally, v2.1 introduces **provider scopes**. A scope is one named account or server such as:
+Instead of configuring “one AWS”, “one Jenkins”, or “one NPM” globally, v2.2 uses **provider scopes** as the only normal deployment credential path. A scope is one named account or server such as:
 
 - `AWS — IndraQ Production`
 - `AWS — Client ABC`
@@ -55,7 +55,7 @@ flowchart LR
 
 Teams often manage several servers, customers and cloud accounts at once. A single provider credential creates ambiguity and unnecessary privilege. Scopes solve both problems.
 
-| Problem | v2.1 behavior |
+| Problem | v2.2 behavior |
 |---|---|
 | Several AWS accounts | Unlimited named AWS scopes |
 | Several Jenkins servers | Unlimited named DEV/PROD Jenkins scopes |
@@ -72,7 +72,7 @@ Teams often manage several servers, customers and cloud accounts at once. A sing
 
 ### Provider scope
 
-One organization-owned provider account/server plus its encrypted management credential and safe metadata.
+One organization-owned provider account/server plus its encrypted management credential and safe metadata. The management secret is used by the Cloud API for provisioning/administration and is **not returned to normal `USE` members**. AWS/NPM/Jenkins users resolve their own native identities instead.
 
 ### Scope membership
 
@@ -228,7 +228,13 @@ indraq prebuild --env dev
 ```bash
 indraq deploy:dev
 # or
-indraq deploy build --env staging
+indraq deploy --env staging
+```
+
+Normal deploys reuse the scopes already saved for that project/environment. Use `--select-scopes` only when you intentionally want to review or change those bindings:
+
+```bash
+indraq deploy --env dev --select-scopes
 ```
 
 ---
@@ -352,7 +358,7 @@ indraq project scopes --env prod
 
 ## Prebuild and deploy
 
-`prebuild` reconciles the project before deployment.
+`prebuild` reconciles the project before deployment. It uses an admin-defined shared environment and saved project scope bindings; it does not offer a project-local custom IPv4 fallback.
 
 ```mermaid
 flowchart TD
@@ -398,9 +404,9 @@ This is useful for projects that existed before IndraQ or where DNS/proxy is man
 ## What `--env` means
 
 ```bash
-indraq deploy build --env dev
-indraq deploy build --env staging
-indraq deploy build --env prod
+indraq deploy --env dev
+indraq deploy --env staging
+indraq deploy --env prod
 ```
 
 The flag selects **IndraQ resource state**:
@@ -491,6 +497,19 @@ Provider identities are removed first. Cloud identity is deleted last. Projects
 
 ## Command reference
 
+### Built-in focused help
+
+The CLI help is aligned with the v2.2 scope-first workflow:
+
+```bash
+indraq help scope
+indraq help users
+indraq help deploy
+indraq help configure
+indraq help aws
+```
+
+
 ### Authentication and diagnostics
 
 | Command | Use |
@@ -523,6 +542,7 @@ Provider identities are removed first. Cloud identity is deleted last. Projects
 | Command | Use |
 |---|---|
 | `indraq user list` | List organization users |
+| `indraq user scopes [email]` | Show your own or a manageable user's assigned scopes |
 | `indraq user create [username]` | Create user + select scopes |
 | `indraq user update [username]` | Password/role operations |
 | `indraq user delete [username]` | Hard delete after scope cleanup |
@@ -540,6 +560,10 @@ Provider identities are removed first. Cloud identity is deleted last. Projects
 | `indraq project scopes --env <env>` | Select project provider scopes |
 | `indraq project add user` | Add project member + synchronize access |
 | `indraq project delete user` | Remove project member |
+| `indraq project rename [name]` | Rename the current project |
+| `indraq project archive` | Archive the current project and block normal deployment access |
+| `indraq project restore` | Restore an archived project |
+| `indraq project delete` | Permanently delete current project metadata |
 | `indraq access add user` | Add selected resource grants |
 | `indraq access delete user` | Remove selected resource grants |
 
@@ -550,7 +574,8 @@ Provider identities are removed first. Cloud identity is deleted last. Projects
 | `indraq prebuild --env <env>` | Reconcile infrastructure |
 | `indraq deploy:dev` | Dev deploy |
 | `indraq deploy:prod` | Prod deploy |
-| `indraq deploy build --env <env>` | Named environment deploy |
+| `indraq deploy --env <env>` | Named environment deploy using saved scope bindings |
+| `indraq deploy --env <env> --select-scopes` | Explicitly review/change project scope bindings before deploy |
 | `indraq jenkins pipelines --stage dev` | List visible pipelines |
 | `indraq jenkins run [job] --stage dev` | Run pipeline with discovered parameters |
 | `indraq jenkins create-deployment` | Bootstrap deployment pipeline |
@@ -633,7 +658,7 @@ Key rules:
 
 ### `fetch failed` while configuring NPM
 
-v2.1 surfaces the underlying network/TLS/authentication error where possible. Verify the URL uses the correct scheme and hostname, then compare with the web login. A browser login does not necessarily prove Node.js trusts the same TLS certificate chain.
+v2.2 surfaces the underlying network/TLS/authentication error where possible. Verify the URL uses the correct scheme and hostname, then compare with the web login. A browser login does not necessarily prove Node.js trusts the same TLS certificate chain.
 
 ### Jenkins says Role Strategy is not active
 
@@ -661,7 +686,7 @@ Run prebuild and choose **Skip** for Route53.
 
 ---
 
-## Cloud API upgrade for v2.1
+## Cloud API upgrade for v2.2
 
 The CLI and Cloud API must be upgraded together.
 
@@ -671,11 +696,12 @@ Apply migrations through:
 cloud-api/sql/001_*.sql
 ...
 cloud-api/sql/008_provider_scopes.sql
+cloud-api/sql/009_scope_user_secrets_and_project_lifecycle.sql
 ```
 
-Then build/restart the Cloud API. The v2.1 migration adds provider scopes, memberships, personal defaults, project/environment bindings and scope-native identity mappings.
+Migration `009` adds encrypted per-user NPM/Jenkins secrets and project archive metadata (`archived_at`, `archived_by`). v2.2 also hardens project/resource authorization and prevents normal `USE` members from resolving shared provider-management credentials.
 
-See [UPGRADE_v2.0_to_v2.1.md](UPGRADE_v2.0_to_v2.1.md) for the release checklist.
+See [UPGRADE_v2.1_to_v2.2.md](UPGRADE_v2.1_to_v2.2.md) and [RELEASE_CHECKS_v2.2.0.md](RELEASE_CHECKS_v2.2.0.md).
 
 ---
 
@@ -700,7 +726,7 @@ npm --prefix cloud-api run build
 <div align="center">
   <img src="docs/assets/indraq-mark.png" alt="IndraQ mark" width="70" />
 
-  **IndraQ CLI v2.1.0**
+  **IndraQ CLI v2.2.0**
 
   Scope-based infrastructure access. Durable projects. Safer deployments.
 </div>

package/cloud-api/.dockerignore

@@ -1,18 +1,18 @@
-node_modules
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-*.log
-.git
-.gitignore
-.indraq
-dist
-build
-.next
-coverage
-.cache
-.vite
-.turbo
-.DS_Store
-Thumbs.db
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+*.log
+.git
+.gitignore
+.indraq
+dist
+build
+.next
+coverage
+.cache
+.vite
+.turbo
+.DS_Store
+Thumbs.db

package/cloud-api/.env.example

@@ -1,14 +1,14 @@
-PORT=4010
-DATABASE_URL=postgresql://indraq:change-me@127.0.0.1:5432/indraq_cloud
-JWT_SECRET=replace-with-64-random-characters
-MASTER_KEY=replace-with-64-hex-characters
-BOOTSTRAP_ADMIN_EMAIL=admin@example.com
-BOOTSTRAP_ADMIN_PASSWORD=change-this-immediately
-
-# Password-reset email (required for `indraq password reset`)
-SMTP_HOST=smtp.example.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=
-SMTP_PASS=
-SMTP_FROM=IndraQ <no-reply@example.com>
+PORT=4010
+DATABASE_URL=postgresql://indraq:change-me@127.0.0.1:5432/indraq_cloud
+JWT_SECRET=replace-with-64-random-characters
+MASTER_KEY=replace-with-64-hex-characters
+BOOTSTRAP_ADMIN_EMAIL=admin@example.com
+BOOTSTRAP_ADMIN_PASSWORD=change-this-immediately
+
+# Password-reset email (required for `indraq password reset`)
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=
+SMTP_PASS=
+SMTP_FROM=IndraQ <no-reply@example.com>

package/cloud-api/Dockerfile

@@ -1,19 +1,19 @@
-FROM node:22-alpine AS build
-WORKDIR /myapp
-# Copy the complete project context. .dockerignore controls all exclusions.
-COPY . .
-RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
-RUN npm run build
-RUN npm prune --omit=dev
-
-FROM node:22-alpine AS runtime
-WORKDIR /myapp
-RUN apk add --no-cache curl
-ENV NODE_ENV=production PORT=4010
-# Copy the complete filtered project from the build stage, including generated
-# build output and production node_modules. No project filenames are guessed.
-COPY --from=build --chown=node:node /myapp ./
-USER node
-EXPOSE 4010
-HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS http://127.0.0.1:4010/health >/dev/null || exit 1
-CMD ["npm", "start"]
+FROM node:22-alpine AS build
+WORKDIR /myapp
+# Copy the complete project context. .dockerignore controls all exclusions.
+COPY . .
+RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM node:22-alpine AS runtime
+WORKDIR /myapp
+RUN apk add --no-cache curl
+ENV NODE_ENV=production PORT=4010
+# Copy the complete filtered project from the build stage, including generated
+# build output and production node_modules. No project filenames are guessed.
+COPY --from=build --chown=node:node /myapp ./
+USER node
+EXPOSE 4010
+HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS http://127.0.0.1:4010/health >/dev/null || exit 1
+CMD ["npm", "start"]

package/cloud-api/README.md

@@ -1,93 +1,93 @@
-# IndraQ Cloud API
-
-Control plane for IndraQ CLI v2.1. The public CLI endpoint is `https://cli.indraq.com`.
-
-## Responsibilities
-
-- authentication and organization RBAC (`user`, `manager`, `admin`)
-- provider scopes for AWS/NPM/Jenkins/GHCR
-- scope USE/MANAGE membership and audited delegation
-- encrypted provider scope secrets
-- per-user scope defaults
-- per-project/environment scope bindings
-- scope-native AWS/NPM/Jenkins identity mappings
-- self-service AWS key rotation and password lifecycle
-- projects, environments and project resource grants
-- audit logging
-
-## Requirements
-
-- Node.js 22+
-- PostgreSQL
-
-## Configure
-
-```bash
-npm install
-cp .env.example .env
-```
-
-Required values include:
-
-```env
-PORT=4010
-DATABASE_URL=postgresql://indraq:change-me@127.0.0.1:5432/indraq_cloud
-JWT_SECRET=replace-with-at-least-32-random-characters
-MASTER_KEY=replace-with-exactly-64-hex-characters
-BOOTSTRAP_ADMIN_EMAIL=admin@example.com
-BOOTSTRAP_ADMIN_PASSWORD=use-a-strong-password
-```
-
-`MASTER_KEY` must remain stable because provider scope secrets use AES-256-GCM encryption.
-
-## Build / run
-
-```bash
-npm run build
-npm start
-```
-
-Development:
-
-```bash
-npm run dev
-```
-
-Numbered migrations in `sql/` are applied automatically at startup. v2.1 adds:
-
-```text
-008_provider_scopes.sql
-```
-
-## v2.1 authorization model
-
-- **Admin** — creates/deletes scopes, grants MANAGE/USE, creates managers/admins, changes organization roles.
-- **Manager** — can add/remove normal users only inside scopes where the manager has MANAGE.
-- **User** — can use only assigned scopes and rotate only their own managed provider credentials.
-
-Scope membership operations and secret resolution require an audit reason and are written to `audit_logs`.
-
-## Provider scopes
-
-`provider_scopes` stores named organization accounts/controllers. `provider_scope_members` controls visibility and use. A user cannot discover a scope simply because it exists.
-
-Related v2.1 tables:
-
-- `provider_scopes`
-- `provider_scope_members`
-- `user_scope_defaults`
-- `project_environment_scopes`
-- `scope_external_accounts`
-- `scope_aws_credentials`
-
-## Projects
-
-Projects and infrastructure are durable. Deleting a user removes scope memberships/native identity mappings and the Cloud identity but retains shared project/environment/resource definitions. Ownership is reassigned before hard deletion where required.
-
-## Security notes
-
-- Passwords are bcrypt-hashed.
-- Provider secrets are encrypted with AES-256-GCM.
-- Secret-resolution responses are `Cache-Control: no-store` and audited.
-- Role/account state is re-read from PostgreSQL on protected requests so demotion/disable takes effect without waiting for JWT expiry.
-- Keep bootstrap credentials and `MASTER_KEY` out of source control.
+# IndraQ Cloud API
+
+Control plane for IndraQ CLI v2.1. The public CLI endpoint is `https://cli.indraq.com`.
+
+## Responsibilities
+
+- authentication and organization RBAC (`user`, `manager`, `admin`)
+- provider scopes for AWS/NPM/Jenkins/GHCR
+- scope USE/MANAGE membership and audited delegation
+- encrypted provider scope secrets
+- per-user scope defaults
+- per-project/environment scope bindings
+- scope-native AWS/NPM/Jenkins identity mappings
+- self-service AWS key rotation and password lifecycle
+- projects, environments and project resource grants
+- audit logging
+
+## Requirements
+
+- Node.js 22+
+- PostgreSQL
+
+## Configure
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Required values include:
+
+```env
+PORT=4010
+DATABASE_URL=postgresql://indraq:change-me@127.0.0.1:5432/indraq_cloud
+JWT_SECRET=replace-with-at-least-32-random-characters
+MASTER_KEY=replace-with-exactly-64-hex-characters
+BOOTSTRAP_ADMIN_EMAIL=admin@example.com
+BOOTSTRAP_ADMIN_PASSWORD=use-a-strong-password
+```
+
+`MASTER_KEY` must remain stable because provider scope secrets use AES-256-GCM encryption.
+
+## Build / run
+
+```bash
+npm run build
+npm start
+```
+
+Development:
+
+```bash
+npm run dev
+```
+
+Numbered migrations in `sql/` are applied automatically at startup. v2.1 adds:
+
+```text
+008_provider_scopes.sql
+```
+
+## v2.1 authorization model
+
+- **Admin** — creates/deletes scopes, grants MANAGE/USE, creates managers/admins, changes organization roles.
+- **Manager** — can add/remove normal users only inside scopes where the manager has MANAGE.
+- **User** — can use only assigned scopes and rotate only their own managed provider credentials.
+
+Scope membership operations and secret resolution require an audit reason and are written to `audit_logs`.
+
+## Provider scopes
+
+`provider_scopes` stores named organization accounts/controllers. `provider_scope_members` controls visibility and use. A user cannot discover a scope simply because it exists.
+
+Related v2.1 tables:
+
+- `provider_scopes`
+- `provider_scope_members`
+- `user_scope_defaults`
+- `project_environment_scopes`
+- `scope_external_accounts`
+- `scope_aws_credentials`
+
+## Projects
+
+Projects and infrastructure are durable. Deleting a user removes scope memberships/native identity mappings and the Cloud identity but retains shared project/environment/resource definitions. Ownership is reassigned before hard deletion where required.
+
+## Security notes
+
+- Passwords are bcrypt-hashed.
+- Provider secrets are encrypted with AES-256-GCM.
+- Secret-resolution responses are `Cache-Control: no-store` and audited.
+- Role/account state is re-read from PostgreSQL on protected requests so demotion/disable takes effect without waiting for JWT expiry.
+- Keep bootstrap credentials and `MASTER_KEY` out of source control.