teamclaws 1.0.3 → 2.0.0

package/dist/target-authorization.js

@@ -0,0 +1,150 @@
+import { createHash, randomUUID } from "node:crypto";
+import { API_V2_BASE, OAUTH_TOKEN_URL } from "./constants.js";
+import { TeamClawsError } from "./errors.js";
+import { errorFromResponse, requestJson, } from "./http.js";
+import { OsMachineKeyProvider, jwkThumbprint, } from "./machine-key.js";
+import { isObject } from "./validation.js";
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+export class TargetAuthorization {
+    fetcher;
+    store;
+    keys;
+    now;
+    constructor(store, fetcher = fetch, keys = new OsMachineKeyProvider(store.root), now = Date.now) {
+        this.store = store;
+        this.fetcher = fetcher;
+        this.keys = keys;
+        this.now = now;
+    }
+    async requireGrant() {
+        const grant = await this.store.readAuthorization();
+        if (!grant)
+            throw new TeamClawsError("login_required", "Approve this CLI at TeamClaws with `teamclaws login` before using a workspace.", { exitCode: 3 });
+        return grant;
+    }
+    async accountHeadersFor(method, url) {
+        return this.accountHeadersForGrant(await this.requireGrant(), method, url);
+    }
+    async accountHeadersForGrant(grant, method, url) {
+        if (new URL(url).origin !== new URL(API_V2_BASE).origin)
+            throw new TeamClawsError("invalid_target", "A TeamClaws issuer URL is required.", { exitCode: 9 });
+        return {
+            "X-TeamClaws-Authorization-Id": grant.authorization_id,
+            DPoP: await this.dpop(grant.machine_key, method, url),
+        };
+    }
+    assertPairing(grant, credential) {
+        if (credential.version !== 2 ||
+            credential.requester_sub !== grant.sub ||
+            credential.authorization_id !== grant.authorization_id ||
+            credential.machine_jkt !== grant.machine_key.jkt ||
+            credential.pairing_id !== credential.device_id) {
+            throw new TeamClawsError("re_pair_required", "This pairing is not bound to the current TeamClaws authorization. Pair this workspace again.", { exitCode: 3 });
+        }
+    }
+    async headersFor(method, url, credential, signal) {
+        const grant = await this.requireGrant();
+        this.assertPairing(grant, credential);
+        if (new URL(url).origin !== credential.origin)
+            throw new TeamClawsError("target_mismatch", "The request target does not match the selected pairing.", { exitCode: 9 });
+        const pairingAuthorization = `Bearer ${credential.device_id}:${credential.device_token}`;
+        const exchangeUrl = `${API_V2_BASE}authorizations/${grant.authorization_id}/proofs/`;
+        const exchange = await requestJson(this.fetcher, exchangeUrl, {
+            method: "POST",
+            headers: {
+                DPoP: await this.dpop(grant.machine_key, "POST", exchangeUrl),
+            },
+            body: {
+                server_id: credential.server_id,
+                pairing_id: credential.pairing_id,
+                scope: "paired:invoke",
+            },
+            ...(signal ? { signal } : {}),
+        });
+        if (exchange.status < 200 || exchange.status >= 300)
+            throw errorFromResponse(exchange, "target_proof_denied");
+        if (!isObject(exchange.body) ||
+            exchange.body.token_type !== "DPoP" ||
+            exchange.body.scope !== "paired:invoke" ||
+            typeof exchange.body.access_token !== "string" ||
+            exchange.body.access_token.length < 16 ||
+            exchange.body.access_token.length > 8192 ||
+            !Number.isInteger(exchange.body.expires_in) ||
+            exchange.body.expires_in < 1 ||
+            exchange.body.expires_in > 300)
+            throw new TeamClawsError("invalid_response", "TeamClaws returned an invalid target proof.", { exitCode: 9 });
+        const proof = exchange.body.access_token;
+        return {
+            Authorization: pairingAuthorization,
+            "X-TeamClaws-Target-Proof": proof,
+            DPoP: await this.dpop(grant.machine_key, method, url, proof, pairingAuthorization),
+        };
+    }
+    async dpop(key, method, url, targetProof, pairingAuthorization) {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+            throw new TeamClawsError("invalid_target", "A canonical HTTPS target is required.", { exitCode: 9 });
+        const header = { typ: "dpop+jwt", alg: "ES256", jwk: key.public_jwk };
+        const payload = {
+            htm: method.toUpperCase(),
+            htu: `${parsed.origin}${parsed.pathname}`,
+            iat: Math.floor(this.now() / 1000),
+            jti: randomUUID(),
+        };
+        if (targetProof !== undefined)
+            payload.ath = hashAscii(targetProof);
+        if (pairingAuthorization !== undefined)
+            payload.pairing_ath = hashAscii(pairingAuthorization);
+        const signingInput = `${base64Json(header)}.${base64Json(payload)}`;
+        return `${signingInput}.${await this.keys.sign(key, signingInput)}`;
+    }
+    async tokenDpop(key) {
+        return this.dpop(key, "POST", OAUTH_TOKEN_URL);
+    }
+}
+export async function requestTargetJson(fetcher, authorization, url, credential, options = {}) {
+    const method = options.method ?? "GET";
+    const attempt = async () => requestJson(fetcher, url, {
+        ...options,
+        headers: {
+            ...options.headers,
+            ...(await authorization.headersFor(method, url, credential, options.signal)),
+        },
+    });
+    const first = await attempt();
+    if (first.status === 401 &&
+        isObject(first.body) &&
+        first.body.error === "target_proof_expired")
+        return attempt();
+    return first;
+}
+export function parseDurableAuthorization(value) {
+    if (!isObject(value) ||
+        value.version !== 2 ||
+        typeof value.authorization_id !== "string" ||
+        !uuid.test(value.authorization_id) ||
+        typeof value.sub !== "string" ||
+        value.sub.length < 1 ||
+        value.sub.length > 255 ||
+        !isObject(value.machine_key) ||
+        !["windows-cng", "posix-file"].includes(String(value.machine_key.provider)) ||
+        typeof value.machine_key.name !== "string" ||
+        !/^teamclaws-cli-[0-9a-f-]{36}$/u.test(value.machine_key.name) ||
+        !isObject(value.machine_key.public_jwk) ||
+        value.machine_key.public_jwk.kty !== "EC" ||
+        value.machine_key.public_jwk.crv !== "P-256" ||
+        typeof value.machine_key.public_jwk.x !== "string" ||
+        typeof value.machine_key.public_jwk.y !== "string" ||
+        typeof value.machine_key.jkt !== "string")
+        throw new TeamClawsError("invalid_credential_file", "The saved CLI authorization is invalid.", { exitCode: 9 });
+    const key = value.machine_key;
+    if (key.jkt !== jwkThumbprint(key.public_jwk))
+        throw new TeamClawsError("invalid_credential_file", "The saved CLI authorization key is invalid.", { exitCode: 9 });
+    return value;
+}
+function hashAscii(value) {
+    return createHash("sha256").update(value, "ascii").digest("base64url");
+}
+function base64Json(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}

package/dist/validation.js

@@ -227,6 +227,12 @@ export function parsePairingCredential(value) {
     return {
         device_id: normalizeUuid(value.device_id, "device identifier"),
         device_token: requireString(value.device_token, "device token", 8_192),
+        pairing_id: normalizeUuid(value.pairing_id, "pairing identifier"),
+        server_id: normalizeUuid(value.server_id, "server identifier"),
+        origin: canonicalWorkspaceOrigin(value.origin),
+        requester_sub: requireString(value.requester_sub, "requester subject", 255),
+        authorization_id: normalizeUuid(value.authorization_id, "authorization identifier"),
+        machine_jkt: requireThumbprint(value.machine_jkt),
         ...(Object.hasOwn(value, "external_chat_capabilities")
             ? {
                 external_chat_capabilities: value.external_chat_capabilities,
@@ -317,13 +323,13 @@ export function parseSafeUserResponse(value) {
             exitCode: 9,
         });
     }
-    assertExactKeys(value, ["id", "email", "display_name", "expires_at", "token_expired"], [], "account response");
-    if (value.token_expired !== false) {
+    assertExactKeys(value, ["id", "email", "display_name", "authorization_id", "authorization_status"], [], "account response");
+    if (value.authorization_status !== "active") {
         throw new TeamClawsError("invalid_response", "TeamClaws returned an invalid account response.", {
             exitCode: 9,
         });
     }
-    requireIsoDate(value.expires_at, "access-token expiry");
+    normalizeUuid(value.authorization_id, "authorization identifier");
     return {
         id: normalizeUuid(value.id, "user identifier"),
         display_name: requireString(value.display_name, "display name", 200),
@@ -405,44 +411,70 @@ export function parseLoginCredential(value) {
 export function parseWorkspaceCredential(value) {
     if (!isObject(value))
         throw invalidCredentialFile();
+    if (value.version === 1)
+        throw legacyPairingError();
     assertExactKeys(value, [
         "version",
         "server_id",
         "origin",
         "display_name",
         "device_id",
+        "pairing_id",
         "device_token",
+        "requester_sub",
+        "authorization_id",
+        "machine_jkt",
         "created_at",
     ], [], "workspace credential file");
-    if (value.version !== 1)
+    if (value.version !== 2)
         throw invalidCredentialFile();
     return {
-        version: 1,
+        version: 2,
         server_id: normalizeUuid(value.server_id),
         origin: canonicalWorkspaceOrigin(value.origin),
         display_name: requireString(value.display_name, "display name", 120),
         device_id: normalizeUuid(value.device_id, "device identifier"),
+        pairing_id: normalizeUuid(value.pairing_id, "pairing identifier"),
         device_token: requireSecret(value.device_token),
+        requester_sub: requireString(value.requester_sub, "requester subject", 255),
+        authorization_id: normalizeUuid(value.authorization_id, "authorization identifier"),
+        machine_jkt: requireThumbprint(value.machine_jkt),
         created_at: requireIsoDate(value.created_at, "credential creation date"),
     };
 }
 export function parseStatusWorkspaceCredential(value, expectedServerId) {
-    if (!isObject(value) || value.version !== 1)
+    if (!isObject(value))
+        throw invalidCredentialFile();
+    if (value.version === 1)
+        throw legacyPairingError();
+    if (value.version !== 2)
         throw invalidCredentialFile();
     const serverId = normalizeUuid(value.server_id);
     if (serverId !== normalizeUuid(expectedServerId))
         throw invalidCredentialFile();
     return {
-        version: 1,
+        version: 2,
         server_id: serverId,
         origin: canonicalWorkspaceOrigin(value.origin),
         display_name: typeof value.display_name === "string" && value.display_name.length > 0
             ? requireString(value.display_name, "display name", 120)
             : "Paired device",
         device_id: normalizeUuid(value.device_id, "device identifier"),
+        pairing_id: normalizeUuid(value.pairing_id, "pairing identifier"),
         device_token: requireSecret(value.device_token),
+        requester_sub: requireString(value.requester_sub, "requester subject", 255),
+        authorization_id: normalizeUuid(value.authorization_id, "authorization identifier"),
+        machine_jkt: requireThumbprint(value.machine_jkt),
     };
 }
+function requireThumbprint(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]{43}$/u.test(value))
+        throw invalidCredentialFile();
+    return value;
+}
+function legacyPairingError() {
+    return new TeamClawsError("re_pair_required", "This saved pairing predates bound CLI authorization. Pair this workspace again.", { exitCode: 3 });
+}
 function requireSecret(value) {
     if (typeof value !== "string" || value.length < 8 || value.length > 8_192) {
         throw invalidCredentialFile();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamclaws",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "Official TeamClaws command-line client and agent skills",
   "license": "PolyForm-Shield-1.0.0",
   "homepage": "https://teamclaws.com",

package/skills/teamclaws-login/SKILL.md

@@ -16,6 +16,7 @@ npx teamclaws login --json
 npx teamclaws login owner@example.com --json
 npx teamclaws auth status --json
 npx teamclaws logout --json
+npx teamclaws logout --revoke --json
 ```
 
 Login uses OAuth 2.0 Device Authorization Grant against www.teamclaws.com. The
@@ -25,13 +26,15 @@ while the user signs in; do not restart it while awaiting approval. Confirm the
 returned account after `login_complete` and exit 0, not after opening a browser.
 Start without an email unless the user supplies one. Optional email is a bind
 sent to TeamClaws, not identity asserted by this process. Never transfer a
-model or harness token into this process. The command-line client stores its own
-protected login credential locally.
+model or harness token into this process. The client stores an authorization ID
+and protected local signing key; temporary OAuth tokens are discarded.
 
 Only treat the fixed structured events as safe. Never expose access tokens,
 refresh tokens, device codes, cookies, or authorization headers.
 
-Logout always removes the local command-line login credential. A
-`local_only_warning` status means local logout succeeded but remote revocation
-could not be confirmed. Completed Clawgate workspace credentials are not
-deleted by logout.
+Ordinary logout removes the local authorization reference. Use `--revoke` only
+when the user asks to revoke this CLI authorization at TeamClaws; the CLI waits
+for confirmation before removing its local reference. If remote revocation is
+uncertain, report that uncertainty and retain the local reference. Completed
+Clawgate workspace credentials are not deleted by logout, but old pairings
+without authorization binding require re-pairing.

package/skills/teamclaws-onboard/SKILL.md

@@ -33,8 +33,10 @@ failures; report the actual result without claiming success.
 ## Choose workspaces
 
 Run `teamclaws servers list --json`. Use only a successful `servers_list` event;
-errors are not empty inventories. Display aliases, retaining `server_id` for
-commands. Explain readiness separately from ownership.
+errors are not empty inventories. Show each server's display name (`alias`) and
+returned `description` to the user, retaining `server_id` for commands. If a
+description is empty or absent, say "No description set." Explain readiness
+separately from ownership.
 
 If discovery emits `server_metadata_prompt`, show its question and explain that
 the owner can always change the server's name and description later. Ask for the
@@ -55,10 +57,11 @@ deliver it when received. Never offer this edit for a shared server whose
   list does not prove an empty account. Ask the user to check their workspaces at
   https://teamclaws.com/app/; only if they confirm they have none, direct them to
   purchase there. Do not claim inventory support is deployed from local code alone.
-- With one pairing-ready workspace, name its alias and ask, “Would you like to
-  pair with **[alias]** now?” Never automatically pair it.
-- With several, list aliases and ask, “Would you like to pair with any of these
-  now?” If aliases repeat, distinguish them using their workspace addresses.
+- With one pairing-ready workspace, show its alias and description and ask,
+  “Would you like to pair with **[alias]** now?” Never automatically pair it.
+- With several, list each alias and description and ask, “Would you like to pair
+  with any of these now?” If aliases repeat, distinguish them using their
+  workspace addresses.
 
 For each selected workspace, follow [teamclaws-pair](../teamclaws-pair/SKILL.md)
 with its stable identifier. A prior explicit selection already authorizes that

package/skills/teamclaws-pair/SKILL.md

@@ -28,7 +28,8 @@ explicit workspace address or server identifier is supplied. On `login_required`
 or `invalid_authentication` (exit 3), explain that login is required. For a
 status-only request, stop. For an authorized connect request, follow the login
 skill and resume after verified login. Do not retry with an explicit target to bypass login.
-The CLI verifies account authentication before workspace contact or approval.
+The CLI requires its saved authorization and matching machine key. Existing
+pairings without this binding require re-pairing.
 
 ## Status-only guardrail
 
@@ -55,9 +56,11 @@ Use `--no-open` only when automatic browser opening is undesirable. The
 `pairing_browser_required` event still provides the safe approval address.
 
 When no selected stable identifier is known, run `teamclaws servers list --json`,
-show aliases and readiness, and ask which workspace the user wants to pair—even
-when only one is available. Pass the selected `server_id`; aliases are display
-labels, not unique command targets. Targetless `teamclaws pair --json` returns
+show each server's display name (`alias`), returned `description`, and readiness,
+and ask which workspace the user wants to pair—even when only one is available.
+If a description is empty or absent, say "No description set." Pass the selected
+`server_id`; aliases are display labels, not unique command targets.
+Targetless `teamclaws pair --json` returns
 `server_selection_required` for any nonempty pairing-ready list and never
 creates approval automatically. Interactive targetless pairing also requires a
 selection. An empty or not-ready list is not proof that the account owns no