impel-cli 0.8.0 → 0.9.0

package/README.md

@@ -121,6 +121,9 @@ impel update [--check] [--skip-apps]         Update EVERYTHING: reinstall the CL
                                              cascade to `app update all` and `skills sync all`
 impel auth [--pat <pat>] [--gateway <url>] [--app <url>]
                                              Store your Impel PAT + URLs
+impel pat create --label <label> [options]    Mint a personal PAT through the control plane
+impel pat create --agent <agent-id> [options]
+                                             Mint a PAT associated with an org agent
 impel token [--tenant <org>]                 Print a selected-tenant bearer
 impel mcp                                    Run the local MCP bridge used by Claude/Codex
 impel claude [claude args...]                Launch isolated Impel Claude Code
@@ -183,6 +186,35 @@ Stores your PAT, gateway base URL, and app/control-plane URL in `~/.config/impel
 impel auth --pat impel_pat_xxxxxxxxxxxx --gateway https://gateway.useimpel.com --app https://www.useimpel.com
 ```
 
+### `impel pat create ...`  (alias `impel pat mint ...`)
+
+Mints a new PAT through the app/control-plane API, authenticated by the PAT
+already stored by `impel auth`. Identity remains the minting authority: the
+control plane verifies the current owner, target-org membership, requested
+scopes, product access, and (when applicable) agent access before it requests a
+new secret. The gateway never mints or verifies PATs.
+
+Use `--label` for a personal token or `--agent` for a token associated with an
+org agent. Agent PATs are still personal credentials: they act as you, are
+org-scoped, and use the same stable `Agent · <agent-id>` association as the agent
+setup UI.
+
+```sh
+impel pat create --label "Rahul's laptop"
+impel pat create --agent support-agent --org acme
+impel pat create --label ci-automation --scopes codex-gateway,tasks --ttl-days 30 --json
+```
+
+`--org` defaults to the selected tenant (`--tenant` is an alias). `--scopes`
+accepts `claude-code-gateway`, `codex-gateway`, and `tasks`; when omitted, the
+control plane chooses the defaults allowed by your access tier. `--ttl-days`
+accepts 1–365 and defaults to 90 days.
+
+The new secret is returned once on stdout and is deliberately **not** written to
+the config file. To rotate this CLI onto it, explicitly run
+`impel auth --pat <new-pat>` after copying it. `--json` includes the raw secret,
+so treat redirected output as a credential.
+
 ### `impel update`
 
 One command brings everything current, in dependency order: the CLI itself
@@ -625,7 +657,7 @@ successful tenant-specific rebuild.
 
 The official Claude and ChatGPT apps remain separate installations and keep
 their normal accounts, updater, profiles, and bundle identities. Each CLI
-release pins exact, tested vendor builds (v0.8.0 pins Claude `1.20186.9` and
+release pins exact, tested vendor builds (v0.9.0 pins Claude `1.20186.9` and
 ChatGPT `26.707.72221`) and their archive SHA-256 digests. The installer reuses
 an existing official app only when its version exactly matches; otherwise it
 downloads the pinned signed archive into Impel's managed vendor cache under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 
 import { cmdAuth } from "./commands/auth.js";
+import { cmdPat } from "./commands/pat.js";
 import { cmdToken } from "./commands/token.js";
 import { cmdUse } from "./commands/use.js";
 import { cmdStatus } from "./commands/status.js";
@@ -34,6 +35,8 @@ Run:
 
 Manage:
   impel auth [--pat <pat>]                    Store your PAT + URLs (--gateway/--app <url>)
+  impel pat create --label <label>            Mint a personal PAT (--org/--scopes/--ttl-days)
+  impel pat create --agent <agent-id>         Mint an org-scoped PAT associated with an agent
   impel tenant list|current|use <org>         List or select the active organization
   impel tasks list|get|create|update|delete   CRUD Impel tickets (aliases: task, ticket[s])
   impel token [--tenant <org>]                Print the selected-tenant bearer
@@ -59,7 +62,7 @@ Native profile switching (advanced; setup never touches native tools):
 
 Env:
   IMPEL_GATEWAY_URL   Default gateway URL when --gateway isn't passed.
-  IMPEL_APP_URL       Default app/control-plane URL for setup, auth, and tasks.
+  IMPEL_APP_URL       Default app/control-plane URL for setup, auth, PATs, and tasks.
   IMPEL_SKIP_UPDATE_CHECK=1   Silence launch-time update notices.
 
 Config file:
@@ -101,6 +104,10 @@ export async function main(argv) {
     case "auth":
       return cmdAuth(rest);
 
+    case "pat":
+    case "pats":
+      return cmdPat(rest);
+
     case "token":
       return cmdToken(rest);
 

package/src/commands/pat.js

@@ -0,0 +1,331 @@
+import { parseFlags } from "../args.js";
+import {
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultAppUrl,
+} from "../config.js";
+import {
+  fetchTenants,
+  normalizeTenantId,
+  PAT_SCOPE_CLAUDE,
+  PAT_SCOPE_CODEX,
+  PAT_SCOPE_TASKS,
+} from "../tenants.js";
+
+const AGENT_PAT_LABEL_PREFIX = "Agent · ";
+const MAX_PAT_LABEL_LENGTH = 120;
+const MAX_PAT_TTL_DAYS = 365;
+const PAT_CREATE_PATH = "/api/cli/pats";
+const PAT_TOKEN_RE = /^impel_pat_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u;
+const PAT_TOKEN_ID_RE = /^[A-Za-z0-9_-]{8,128}$/u;
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,111}$/u;
+const CONTROL_CHARACTER_RE = /[\u0000-\u001F\u007F-\u009F]/u;
+const PAT_SCOPES = [PAT_SCOPE_CLAUDE, PAT_SCOPE_CODEX, PAT_SCOPE_TASKS];
+const PAT_SCOPE_SET = new Set(PAT_SCOPES);
+const FLAG_NAMES = new Set([
+  "agent",
+  "app",
+  "help",
+  "json",
+  "label",
+  "org",
+  "scopes",
+  "tenant",
+  "ttl-days",
+]);
+
+const HELP = `impel pat - mint a personal access token through Impel
+
+Usage:
+  impel pat create --label <label> [options]
+  impel pat create --agent <agent-id> [options]
+
+Aliases:
+  impel pats ...
+  impel pat mint ...
+
+Options:
+  --org <org>          Target org. Defaults to the selected tenant.
+  --tenant <org>       Alias for --org.
+  --scopes <csv>       Requested scopes: ${PAT_SCOPES.join(", ")}.
+                       Defaults are chosen by the control plane for your access tier.
+  --ttl-days <days>    Expiry from 1 to ${MAX_PAT_TTL_DAYS} days. Default: 90.
+  --app <url>          Override the app/control-plane URL for this command.
+  --json               Print the created PAT and metadata as JSON.
+
+The stored PAT authenticates this request. The control plane verifies the owner,
+organization membership, requested scopes, and agent access before identity mints
+the new secret. The new PAT is shown once and is not stored automatically.
+`;
+
+class PatCommandError extends Error {}
+
+function fail(message) {
+  throw new PatCommandError(message);
+}
+
+function flagSpec() {
+  return {
+    agent: { type: "string" },
+    app: { type: "string" },
+    help: { type: "boolean" },
+    json: { type: "boolean" },
+    label: { type: "string" },
+    org: { type: "string" },
+    scopes: { type: "string" },
+    tenant: { type: "string" },
+    "ttl-days": { type: "string" },
+  };
+}
+
+function requireConfig(flags) {
+  const config = loadConfig();
+  if (!config?.pat) {
+    fail("impel pat: not authenticated. Run `impel setup` (or `impel auth`) first.");
+  }
+
+  const appUrl = normalizeGatewayUrl(flags.app || config.appUrl || resolveDefaultAppUrl());
+  let parsed;
+  try {
+    parsed = new URL(appUrl);
+  } catch {
+    fail("impel pat: --app must be an HTTP or HTTPS URL.");
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    || parsed.username
+    || parsed.password
+    || parsed.pathname !== "/"
+    || parsed.search
+    || parsed.hash
+  ) {
+    fail("impel pat: --app must be a bare HTTP or HTTPS origin without credentials, a path, query, or fragment.");
+  }
+  return { appUrl, config };
+}
+
+function requestedScopes(value) {
+  if (value === undefined) return undefined;
+  const requested = String(value)
+    .split(",")
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+  if (requested.length === 0) {
+    fail("impel pat: --scopes must contain at least one scope.");
+  }
+  for (const scope of requested) {
+    if (!PAT_SCOPE_SET.has(scope)) {
+      fail(`impel pat: unknown scope "${redactSecretText(scope)}".`);
+    }
+  }
+  const requestedSet = new Set(requested);
+  return PAT_SCOPES.filter((scope) => requestedSet.has(scope));
+}
+
+function requestedTtlDays(value) {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/u.test(String(value))) {
+    fail(`impel pat: --ttl-days must be an integer from 1 to ${MAX_PAT_TTL_DAYS}.`);
+  }
+  const days = Number(value);
+  if (!Number.isSafeInteger(days) || days < 1 || days > MAX_PAT_TTL_DAYS) {
+    fail(`impel pat: --ttl-days must be an integer from 1 to ${MAX_PAT_TTL_DAYS}.`);
+  }
+  return days;
+}
+
+function requestedSubject(flags) {
+  const agentId = flags.agent === undefined ? null : String(flags.agent).trim();
+  const personalLabel = flags.label === undefined ? null : String(flags.label).trim();
+  if (agentId !== null && personalLabel !== null) {
+    fail("impel pat create: use either --label for a personal PAT or --agent for an agent PAT, not both.");
+  }
+  if (agentId !== null) {
+    if (!AGENT_ID_RE.test(agentId)) {
+      fail("impel pat create: --agent must be a valid agent id (letters, numbers, dots, dashes, or underscores).");
+    }
+    const label = `${AGENT_PAT_LABEL_PREFIX}${agentId}`;
+    if (label.length > MAX_PAT_LABEL_LENGTH) {
+      fail(`impel pat create: the generated agent label exceeds ${MAX_PAT_LABEL_LENGTH} characters.`);
+    }
+    return { agentId, kind: "agent", label };
+  }
+
+  if (!personalLabel) {
+    fail("impel pat create: --label is required for a personal PAT; use --agent <id> for an agent PAT.");
+  }
+  if (personalLabel.length > MAX_PAT_LABEL_LENGTH || CONTROL_CHARACTER_RE.test(personalLabel)) {
+    fail(`impel pat create: --label must be 1 to ${MAX_PAT_LABEL_LENGTH} characters without control characters.`);
+  }
+  return { agentId: null, kind: "personal", label: personalLabel };
+}
+
+async function requestedOrgId(flags, config, appUrl) {
+  if (flags.org !== undefined && flags.tenant !== undefined && flags.org !== flags.tenant) {
+    fail("impel pat: --org and --tenant must name the same org when both are passed.");
+  }
+  const requested = flags.org ?? flags.tenant;
+  try {
+    if (requested !== undefined) return normalizeTenantId(requested);
+    if (config.tenantId) return normalizeTenantId(config.tenantId);
+    const listing = await fetchTenants({ ...config, appUrl });
+    return listing.defaultTenantId;
+  } catch (error) {
+    fail(`impel pat: could not resolve the target org: ${redactSecretText(error?.message || error)}`);
+  }
+}
+
+function timestamp(value, { nullable = false } = {}) {
+  if (nullable && value === null) return null;
+  if (!Number.isSafeInteger(value) || Number.isNaN(new Date(value).getTime())) return undefined;
+  return value;
+}
+
+function normalizeCreatedPat(payload, expected) {
+  const value = payload?.pat && typeof payload.pat === "object" ? payload.pat : payload;
+  if (!value || typeof value !== "object") return null;
+  const scopes = Array.isArray(value.scopes)
+    && value.scopes.every((scope) => typeof scope === "string" && PAT_SCOPE_SET.has(scope))
+    ? [...new Set(value.scopes)]
+    : null;
+  const createdAt = timestamp(value.createdAt);
+  const expiresAt = timestamp(value.expiresAt, { nullable: true });
+  if (
+    typeof value.token !== "string"
+    || !PAT_TOKEN_RE.test(value.token)
+    || typeof value.tokenId !== "string"
+    || !PAT_TOKEN_ID_RE.test(value.tokenId)
+    || value.orgId !== expected.orgId
+    || value.label !== expected.label
+    || !scopes
+    || createdAt === undefined
+    || expiresAt === undefined
+  ) {
+    return null;
+  }
+  return {
+    token: value.token,
+    tokenId: value.tokenId,
+    orgId: value.orgId,
+    label: value.label,
+    scopes,
+    createdAt,
+    expiresAt,
+  };
+}
+
+async function createPat({ appUrl, currentPat, body }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10_000);
+  let response;
+  try {
+    response = await fetch(new URL(PAT_CREATE_PATH, appUrl), {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${currentPat}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const message = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+    fail(`impel pat: could not reach ${appUrl}: ${redactSecretText(message)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  const text = await response.text();
+  let payload = null;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = null;
+  }
+  if (!response.ok) {
+    if (response.status === 404) {
+      fail(`impel pat: PAT minting is not available on ${appUrl}; update the Impel control plane and try again.`);
+    }
+    const message = redactSecretText(payload?.error || `${response.status} ${response.statusText}`.trim());
+    fail(`impel pat: ${message}`);
+  }
+
+  const created = normalizeCreatedPat(payload, body);
+  if (!created) {
+    fail("impel pat: the control plane returned an invalid PAT creation response; the secret was not displayed.");
+  }
+  return created;
+}
+
+function printCreatedPat(created, subject, json) {
+  if (json) {
+    console.log(JSON.stringify({
+      kind: subject.kind,
+      ...(subject.agentId ? { agentId: subject.agentId } : {}),
+      ...created,
+    }, null, 2));
+    return;
+  }
+
+  if (subject.kind === "agent") {
+    console.log(`Created an agent PAT for ${subject.agentId} in ${created.orgId}.`);
+  } else {
+    console.log(`Created personal PAT ${JSON.stringify(created.label)} in ${created.orgId}.`);
+  }
+  console.log(`Scopes:  ${created.scopes.join(", ") || "none"}`);
+  console.log(`Expires: ${created.expiresAt === null ? "never" : new Date(created.expiresAt).toISOString()}`);
+  console.log("");
+  console.log("Copy this token now. Impel cannot show the secret again:");
+  console.log(created.token);
+}
+
+export async function cmdPat(argv) {
+  const [action, ...rest] = argv;
+  if (!action || action === "help" || action === "--help" || action === "-h") {
+    console.log(HELP);
+    return;
+  }
+  if (action !== "create" && action !== "mint") {
+    console.error(`impel pat: unknown subcommand "${redactSecretText(action)}".`);
+    console.error("  Use `impel pat create --label <label>` or `impel pat create --agent <agent-id>`.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const { flags, positionals } = parseFlags(rest, flagSpec());
+  try {
+    if (flags.help) {
+      console.log(HELP);
+      return;
+    }
+    const unknownFlag = Object.keys(flags).find((name) => !FLAG_NAMES.has(name));
+    if (unknownFlag) fail(`impel pat: unknown option --${redactSecretText(unknownFlag)}.`);
+    if (positionals.length > 0) {
+      fail(`impel pat create: unexpected argument "${redactSecretText(positionals[0])}".`);
+    }
+
+    const subject = requestedSubject(flags);
+    const scopes = requestedScopes(flags.scopes);
+    const ttlDays = requestedTtlDays(flags["ttl-days"]);
+    const { appUrl, config } = requireConfig(flags);
+    const orgId = await requestedOrgId(flags, config, appUrl);
+    const body = {
+      orgId,
+      label: subject.label,
+      ...(subject.agentId ? { agentId: subject.agentId } : {}),
+      ...(scopes ? { scopes } : {}),
+      ...(ttlDays ? { ttlDays } : {}),
+    };
+    const created = await createPat({ appUrl, currentPat: config.pat, body });
+    printCreatedPat(created, subject, flags.json === true);
+  } catch (error) {
+    if (error instanceof PatCommandError) {
+      console.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}