@fulldivevr/workcord-cli 1.0.0 → 1.1.0

package/README.md

@@ -21,9 +21,10 @@ npx @fulldivevr/workcord-cli --help
 | Setting | How |
 | --- | --- |
 | Base URL | `WORKCORD_API_URL` env var or `--base-url <url>` — **required, no default** |
-| Signing secret | `WORKCORD_JWT_SECRET` env var **only** — never a flag |
+| User token | `WORKCORD_TOKEN` env var **only** — a per-user access token from `workcord auth login`; the normal way to authenticate |
+| Signing secret | `WORKCORD_JWT_SECRET` env var **only** — never a flag; privileged, enables `--as` impersonation |
 | Internal admin key | `WORKCORD_INTERNAL_API_KEY`, internal commands only |
-| Acting user | `--as <userId>`, per invocation |
+| Acting user | `--as <userId>`, per invocation — only with `WORKCORD_JWT_SECRET` |
 
 Base URL must be a bare origin (scheme + host, no path). The `/api/v1` prefix
 is added by the CLI.
@@ -40,33 +41,46 @@ is added by the CLI.
 
 ```bash
 export WORKCORD_API_URL=https://work-rooms-api.wizeup.app
-export WORKCORD_JWT_SECRET=<the server's JWT_SECRET>
+export WORKCORD_TOKEN=<token from `workcord auth login`>
 
-workcord --as <userId> users get-me
+workcord users get-me
 ```
 
 Output is JSON on stdout, errors on stderr, non-zero exit on failure.
 
 ### How auth works
 
-Three distinct modes.
+Every request carries a bearer token. There are two ways to get one, and one
+extra header for internal admin routes.
 
-**1. Normal user login (email code).** Deployed WorkCord/VIA stacks run with
-`ENABLE_EMAIL_AUTH=true` and mail a 6-digit code:
+**1. A real user token (normal path).** Log in once, export the token, and every
+command runs as that user with exactly that user's permissions:
 
 ```bash
 workcord auth login --email you@company.com
-# → code arrives by email, CLI prompts for it, prints { token, accessToken, refreshToken, user, isNewUser }
+# → code arrives by email, CLI prompts for it, prints
+#   { token, accessToken, refreshToken, user, isNewUser } on stdout
+#   and an `export WORKCORD_TOKEN=...` hint on stderr
+
+export WORKCORD_TOKEN=<token>
+workcord users get-me
+workcord whoami          # → {"mode":"token","userId":"...","source":"WORKCORD_TOKEN"}
 ```
 
-Non-interactive (no TTY) it prints a `sessionId` and you finish with:
+`WORKCORD_TOKEN` is sent as-is in `Authorization: Bearer`; the CLI never signs
+anything in this mode and `--as` is not needed. This is the least-privilege
+setup and the right one for agents.
+
+Non-interactive (no TTY) `auth login --email` prints a `sessionId` and you
+finish with:
 
 ```bash
 workcord auth verify-email --session-id <id> --code 123456
 ```
 
 Email login returns `accessToken`; phone/social login returns `token`. The CLI
-emits both fields on either path so callers can read one consistently.
+emits both fields on either path so callers can read one consistently — either
+value works as `WORKCORD_TOKEN`.
 
 Email auth is domain-restricted. WorkCord prod and VIA both allow
 `fulldive.com`, `via.com`, `via.com.tw`, `viatech.com.cn`, `*.tvbs.com`,
@@ -78,16 +92,37 @@ Email auth is domain-restricted. WorkCord prod and VIA both allow
 set `AUTH_PHONE_OTP_DEV_BYPASS`, so `POST /auth/send-otp` returns 503
 `OTP_NOT_AVAILABLE` — the CLI turns that into an explicit "use `--email`" error.
 
-**2. Impersonation / agent auth.** With `WORKCORD_JWT_SECRET` set, the global
-`--as <userId>` flag mints an HS256 JWT locally (payload `{userId, id}`, 60-day
-expiry) instead of logging in. `WORKCORD_JWT_SECRET` must equal the **server's
-`JWT_SECRET`** env var — the names deliberately differ, and this is the most
-common setup mistake.
+Tokens expire. On `401`, log in again and re-export `WORKCORD_TOKEN`.
+
+**2. Local minting / impersonation (privileged, trusted CI only).** With
+`WORKCORD_JWT_SECRET` set, the global `--as <userId>` flag mints an HS256 JWT
+locally (payload `{userId, id}`, 60-day expiry) instead of logging in.
+`WORKCORD_JWT_SECRET` must equal the **server's `JWT_SECRET`** env var — the
+names deliberately differ, and this is the most common setup mistake.
+
+```bash
+export WORKCORD_JWT_SECRET=<the server's JWT_SECRET>
+workcord --as <userId> users get-me
+```
 
 Same secret on both sides means the CLI can act as **any** user, with no
 password and no server-side check. Treat it as privileged signing material:
 keep it out of source control, package metadata, logs, screenshots and public
-examples, and run this CLI only from trusted machines and CI jobs.
+examples, and run this CLI only from trusted machines and CI jobs. Prefer
+`WORKCORD_TOKEN` unless you actually need to switch identities.
+
+Resolution order, in one place (`resolveAuth` in `src/auth.ts`):
+
+| Situation | Result |
+| --- | --- |
+| `--as <userId>` passed, `WORKCORD_JWT_SECRET` set | mint and impersonate that user |
+| `--as <userId>` passed, no secret | error — set the secret or drop `--as` |
+| no `--as`, `WORKCORD_TOKEN` set | send that token verbatim |
+| no `--as`, only `WORKCORD_JWT_SECRET` set | error — `--as <userId>` required |
+| neither set | error naming both options |
+
+`--as` wins over `WORKCORD_TOKEN` when both are available: passing it is an
+explicit statement of impersonation intent.
 
 **3. Internal admin routes.** `WORKCORD_INTERNAL_API_KEY` is sent as the
 `x-internal-key` header; the server compares it to its own `INTERNAL_API_KEY`.
@@ -99,6 +134,9 @@ Required for `/internal/*` and the jesuscord admin routes. Treat it like the sig
 workcord [--as <userId>] <namespace> <command> [flags]
 ```
 
+`--as` is only needed when minting with `WORKCORD_JWT_SECRET`; with
+`WORKCORD_TOKEN` set, omit it everywhere.
+
 - `workcord --help` lists namespaces.
 - `workcord <namespace> --help` lists that namespace's commands.
 - `workcord <namespace> <command> --help` shows the command's flags.
@@ -133,8 +171,8 @@ profile fields.
 
 Server auto-extracts mention tokens from visible `@Name` text. Prefer
 `messages send-text --mention-user USER_ID` so the CLI resolves the room
-member's display name and avoids exposing raw user ids. `auth login` is the
-only semantic command that doesn't take `--as` (it returns one).
+member's display name and avoids exposing raw user ids. `auth login` never
+takes `--as` — it is how you obtain a `WORKCORD_TOKEN` in the first place.
 
 ### Error handling
 
@@ -196,8 +234,9 @@ from each room, merges them by `sentAt` descending, and includes
 
 **Switch user identity per call:**
 
-The CLI is stateless — `--as <userId>` per invocation. One process can act as
-100 users by changing the flag.
+The CLI is stateless. With `WORKCORD_TOKEN` the identity is the token's owner;
+swap the env var to swap users. With `WORKCORD_JWT_SECRET` one process can act
+as 100 users by changing `--as <userId>` per invocation.
 
 **Onboard a fresh agent identity:**
 
@@ -255,7 +294,7 @@ without running `regen` if you don't need the latest server changes.
 ```
 src/
 ├── cli.ts                  commander entry, global --as flag
-├── auth.ts                 mints HS256 JWT from --as
+├── auth.ts                 auth resolution: WORKCORD_TOKEN vs minted --as JWT
 ├── client.ts               fetch wrapper (JSON + multipart)
 ├── commands/               hand-written semantic commands
 └── generated/              auto-generated from openapi.json
@@ -266,7 +305,9 @@ scripts/
 ├── sync-spec.ts            backend build → openapi.json
 └── generate-commands.ts    spec → commander commands
 
-tests/smoke.sh              hermetic end-to-end test
+tests/
+├── auth.test.ts            node --test suite for auth resolution
+└── smoke.sh                end-to-end test, needs a live server
 ```
 
 ### Adding a hand-written semantic command
@@ -283,7 +324,8 @@ flags (e.g. typed fields instead of an opaque `--body`):
 ### Testing
 
 ```bash
-npm run smoke
+npm test           # hermetic, no network — auth resolution rules
+npm run smoke      # end-to-end, needs a live server
 ```
 
 Hermetic end-to-end suite (creates two fresh users per run via OTP, exercises
@@ -297,14 +339,14 @@ Publishing is a manual maintainer action — there is no auto-publish CI.
 
 1. `npm run regen` — refresh the spec and generated commands; commit the diff.
 2. `npm run typecheck`
-3. `npm run build`
+3. `npm test` then `npm run build`
 4. `npm pack --dry-run` — confirm the file list is exactly `dist/**/*.js`,
    `README.md`, `LICENSE`, `package.json`. No sources, no `openapi.json`, no
    `.npmrc`.
 5. Smoke: `node dist/cli.js --help` and `node dist/cli.js --version`.
 6. Bump `version` in `package.json`, then `npm publish`.
 
-`prepack` re-runs `typecheck` + `build`, so steps 2–3 also gate the publish.
+`prepack` re-runs `typecheck` + `test` + `build`, so steps 2–3 also gate the publish.
 
 ## License
 

package/dist/auth.js

@@ -1,9 +1,43 @@
 import jwt from "jsonwebtoken";
-export function mintToken(userId) {
-    const secret = process.env.WORKCORD_JWT_SECRET;
-    if (!secret) {
+export function actingUserId(program) {
+    return program.opts().as;
+}
+export function mintToken(userId, secret) {
+    const key = secret ?? process.env.WORKCORD_JWT_SECRET;
+    if (!key) {
         throw new Error("WORKCORD_JWT_SECRET not set");
     }
-    return jwt.sign({ userId, id: userId }, secret, { algorithm: "HS256", expiresIn: "60d" });
+    return jwt.sign({ userId, id: userId }, key, { algorithm: "HS256", expiresIn: "60d" });
+}
+export function resolveAuth(asUserId, env = process.env) {
+    const secret = env.WORKCORD_JWT_SECRET?.trim() || undefined;
+    const token = env.WORKCORD_TOKEN?.trim() || undefined;
+    if (asUserId) {
+        if (!secret) {
+            throw new Error("--as <userId> mints a token and needs WORKCORD_JWT_SECRET. Set it, or drop --as and set WORKCORD_TOKEN to a token from `workcord auth login`.");
+        }
+        const minted = mintToken(asUserId, secret);
+        return { mode: "minted", bearer: `Bearer ${minted}`, token: minted, userId: asUserId };
+    }
+    if (token) {
+        return { mode: "token", bearer: `Bearer ${token}`, token };
+    }
+    if (secret) {
+        throw new Error("--as <userId> is required when authenticating with WORKCORD_JWT_SECRET");
+    }
+    throw new Error("No credentials. Set WORKCORD_TOKEN to a token from `workcord auth login`, or set WORKCORD_JWT_SECRET and pass --as <userId>.");
+}
+export function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=auth.js.map

package/dist/client.js

@@ -1,4 +1,4 @@
-import { mintToken } from "./auth.js";
+import { resolveAuth } from "./auth.js";
 let baseUrlOverride;
 export function setBaseUrlOverride(url) {
     baseUrlOverride = url;
@@ -52,6 +52,7 @@ async function fetchWithRetry(build) {
     throw lastErr;
 }
 export async function call({ method = "GET", path, query, body, headers, asUserId }) {
+    const { bearer } = resolveAuth(asUserId);
     const base = getBaseUrl();
     const url = new URL(base + path);
     if (query) {
@@ -60,14 +61,13 @@ export async function call({ method = "GET", path, query, body, headers, asUserI
                 url.searchParams.set(k, String(v));
         }
     }
-    const token = mintToken(asUserId);
     const res = await fetchWithRetry(() => ({
         url,
         init: {
             method,
             headers: {
                 "content-type": "application/json",
-                authorization: `Bearer ${token}`,
+                authorization: bearer,
                 ...headers,
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -92,9 +92,9 @@ function safeJson(s) {
     }
 }
 export async function callMultipart({ path, asUserId, fields, file }) {
+    const { bearer } = resolveAuth(asUserId);
     const base = getBaseUrl();
     const url = base + path;
-    const token = mintToken(asUserId);
     const res = await fetchWithRetry(() => {
         const fd = new FormData();
         if (fields) {
@@ -107,7 +107,7 @@ export async function callMultipart({ path, asUserId, fields, file }) {
             url,
             init: {
                 method: "POST",
-                headers: { authorization: `Bearer ${token}` },
+                headers: { authorization: bearer },
                 body: fd,
             },
         };

package/dist/commands/auth.js

@@ -38,7 +38,11 @@ function normalize(data) {
     return r;
 }
 function emit(data) {
-    process.stdout.write(JSON.stringify(normalize(data)) + "\n");
+    const result = normalize(data);
+    process.stdout.write(JSON.stringify(result) + "\n");
+    if (result.token) {
+        process.stderr.write(`export WORKCORD_TOKEN=${result.token}\n`);
+    }
 }
 async function promptCode() {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -96,7 +100,8 @@ export function registerAuth(program) {
         .command("login")
         .description("End-to-end login. Returns { token, accessToken, refreshToken, user, isNewUser }. " +
         "--email uses the emailed 6-digit code (deployed WorkCord/VIA); --phone uses OTP " +
-        "(local/RoomCord only). Does NOT use --as / WORKCORD_JWT_SECRET — the server mints the token.")
+        "(local/RoomCord only). Does NOT use --as / WORKCORD_JWT_SECRET — the server mints the token. " +
+        "Export the returned token as WORKCORD_TOKEN to authenticate every other command.")
         .option("--email <address>", "email address (mutually exclusive with --phone)")
         .option("--phone <e164>", 'phone number in E.164 format (e.g. "+14155550199")')
         .option("--code <code>", "verification code; prompted interactively for --email when omitted")

package/dist/commands/challenges.js

@@ -1,11 +1,6 @@
+import { actingUserId } from "../auth.js";
 import { call } from "../client.js";
 import { getOrCreateGroup } from "./_group.js";
-function currentUser(program) {
-    const { as } = program.opts();
-    if (!as)
-        throw new Error("--as <userId> is required");
-    return as;
-}
 /**
  * Custom challenge commands that are NOT covered by the OpenAPI-generated
  * commands (src/generated/commands/challenges.ts). Everything else — create,
@@ -34,7 +29,7 @@ export function registerChallenges(program) {
             const data = (await call({
                 method: "POST",
                 path: `/api/v1/challenges/${encodeURIComponent(opts.id)}/regenerate-cards?offset=${offset}&limit=10`,
-                asUserId: currentUser(program),
+                asUserId: actingUserId(program),
                 body: {},
             }));
             totals.total = data.total;

package/dist/commands/custom-agents.js

@@ -1,12 +1,7 @@
 import { readFileSync } from "node:fs";
+import { actingUserId } from "../auth.js";
 import { call } from "../client.js";
 import { getOrCreateGroup } from "./_group.js";
-function currentUser(program) {
-    const { as } = program.opts();
-    if (!as)
-        throw new Error("--as <userId> is required");
-    return as;
-}
 function bool(v, name) {
     if (v === undefined)
         return undefined;
@@ -54,7 +49,7 @@ export function registerCustomAgents(program) {
         const data = await call({
             method: "POST",
             path: "/api/v1/agents",
-            asUserId: currentUser(program),
+            asUserId: actingUserId(program),
             body: {
                 name: opts.name,
                 description: opts.description,
@@ -111,7 +106,7 @@ export function registerCustomAgents(program) {
         const data = await call({
             method: "PATCH",
             path: `/api/v1/agents/${encodeURIComponent(opts.agent)}`,
-            asUserId: currentUser(program),
+            asUserId: actingUserId(program),
             body,
         });
         process.stdout.write(JSON.stringify(data) + "\n");

package/dist/commands/dm.js

@@ -1,3 +1,4 @@
+import { actingUserId } from "../auth.js";
 import { call } from "../client.js";
 import { getOrCreateGroup } from "./_group.js";
 export function registerDm(program) {
@@ -10,9 +11,7 @@ export function registerDm(program) {
         .requiredOption("--text <text>", "message body — mention users with @userId inline")
         .option("--reply-to <messageId>", "parent message id (for threaded replies)")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const dm = (await call({
             method: "POST",
             path: "/api/v1/dm/start",

package/dist/commands/messages.js

@@ -1,3 +1,4 @@
+import { actingUserId } from "../auth.js";
 import { call } from "../client.js";
 import { getOrCreateGroup } from "./_group.js";
 const MAX_LIMIT = 500;
@@ -113,9 +114,7 @@ export function registerMessages(program) {
         .option("--attachments <urls>", "comma-separated GCS URLs (use `workcord rooms upload-image-file` to get URLs first)")
         .option("--no-shadow-guidance", "do not opt in to Shadow guidance cards")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const mentions = await resolveMentions(opts.room, as, opts.mentionUser);
         const content = mentions.length > 0 ? `${mentions.map((m) => `@${m.name}`).join(" ")} ${opts.text}` : opts.text;
         const body = {
@@ -143,9 +142,7 @@ export function registerMessages(program) {
         .option("--after <iso>", "only messages with sentAt > this ISO timestamp; overrides --cursor server-side")
         .option("--filter <filter>", `one of: ${Array.from(MESSAGE_FILTERS).join(", ")}`)
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const data = await call({
             method: "GET",
             path: `/api/v1/rooms/${encodeURIComponent(opts.room)}/messages`,
@@ -169,9 +166,7 @@ export function registerMessages(program) {
         .option("--limit <n>", `page size, 1-${MAX_PAGE_LIMIT}`, "20")
         .option("--cursor <iso>", "pagination cursor from the previous page's cursor")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const data = await call({
             method: "GET",
             path: `/api/v1/rooms/${encodeURIComponent(opts.room)}/messages/${encodeURIComponent(opts.message)}/thread`,
@@ -190,9 +185,7 @@ export function registerMessages(program) {
         .requiredOption("--room <roomId>", "target room id")
         .requiredOption("--message <messageId>", "thread root message id")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const data = await call({
             method: "POST",
             path: `/api/v1/rooms/${encodeURIComponent(opts.room)}/messages/${encodeURIComponent(opts.message)}/thread/read`,
@@ -209,9 +202,7 @@ export function registerMessages(program) {
         .option("--limit <n>", "max messages per page (server caps at 100)", "50")
         .option("--max-pages <n>", "safety cap on pages walked back", "20")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const sinceMs = new Date(opts.since).getTime();
         if (Number.isNaN(sinceMs))
             throw new Error(`--since not a valid ISO timestamp: ${opts.since}`);
@@ -259,9 +250,7 @@ export function registerMessages(program) {
         .option("--inbox-category <value>", "room inbox category filter")
         .option("--no-shadow-guidance", "do not opt in to Shadow guidance cards")
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const limit = parsePositiveInt(opts.limit, "--limit", MAX_LIMIT);
         const perRoomLimit = parsePositiveInt(opts.perRoomLimit, "--per-room-limit", MAX_PAGE_LIMIT);
         const roomPageLimit = parsePositiveInt(opts.roomPageLimit, "--room-page-limit", MAX_PAGE_LIMIT);
@@ -345,9 +334,7 @@ export function registerMessages(program) {
         .requiredOption("--message <messageId>", "target message")
         .requiredOption("--emoji <type>", 'reaction type — emoji or id (e.g. "👍" or "thumbs_up")')
         .action(async (opts) => {
-        const { as } = program.opts();
-        if (!as)
-            throw new Error("--as <userId> is required");
+        const as = actingUserId(program);
         const data = await call({
             method: "POST",
             path: `/api/v1/rooms/${encodeURIComponent(opts.room)}/messages/${encodeURIComponent(opts.message)}/reactions`,

package/dist/commands/room-agents.js

@@ -1,11 +1,6 @@
+import { actingUserId } from "../auth.js";
 import { call } from "../client.js";
 import { getOrCreateGroup } from "./_group.js";
-function currentUser(program) {
-    const { as } = program.opts();
-    if (!as)
-        throw new Error("--as <userId> is required");
-    return as;
-}
 function bool(v, name) {
     if (v === undefined)
         return undefined;
@@ -24,7 +19,7 @@ export function registerRoomAgents(program) {
         .requiredOption("--agent <agentId>", "hosted custom/system agent id")
         .option("--reply-in-thread <true|false>", "whether the agent replies in threads")
         .action(async (opts) => {
-        const asUserId = currentUser(program);
+        const asUserId = actingUserId(program);
         const installed = (await call({
             method: "POST",
             path: `/api/v1/rooms/${encodeURIComponent(opts.room)}/agents/install/${encodeURIComponent(opts.agent)}`,