teamclaws 1.0.4 → 2.0.1

package/dist/pairing.js

@@ -4,6 +4,7 @@ import { PAIRING_STATUS_TIMEOUT_MS } from "./constants.js";
 import { errorFromResponse, requestJson, } from "./http.js";
 import { directTargetUrl, isObject, parsePairingCredential, parseVerifiedDevice, parseVerifiedWorkspace, requireInteger, } from "./validation.js";
 import { openExternalBrowser } from "./browser.js";
+import { TargetAuthorization, requestTargetJson, } from "./target-authorization.js";
 export class PairingClient {
     fetcher;
     store;
@@ -11,6 +12,7 @@ export class PairingClient {
     openBrowser;
     now;
     wait;
+    authorization;
     constructor(options) {
         this.fetcher = options.fetcher ?? fetch;
         this.store = options.store;
@@ -18,13 +20,18 @@ export class PairingClient {
         this.openBrowser = options.openBrowser ?? openExternalBrowser;
         this.now = options.now ?? Date.now;
         this.wait = options.wait ?? waitFor;
+        this.authorization =
+            options.authorization ??
+                new TargetAuthorization(this.store, this.fetcher);
     }
     async status(target, signal) {
         let credential;
         try {
             credential = await this.store.findWorkspace(target);
         }
-        catch {
+        catch (error) {
+            if (error instanceof TeamClawsError && error.code === "re_pair_required")
+                throw error;
             this.output.pairingStatus("unreachable");
             return "unreachable";
         }
@@ -38,10 +45,8 @@ export class PairingClient {
             display_name: credential.display_name,
         };
         try {
-            const response = await requestJson(this.fetcher, `${credential.origin}/teamclaws-admin/api/device-pairings/me/`, {
-                headers: {
-                    Authorization: `Bearer ${credential.device_id}:${credential.device_token}`,
-                },
+            const url = `${credential.origin}/teamclaws-admin/api/device-pairings/me/`;
+            const response = await requestTargetJson(this.fetcher, this.authorization, url, credential, {
                 timeoutMs: PAIRING_STATUS_TIMEOUT_MS,
                 ...(signal ? { signal } : {}),
             });
@@ -63,6 +68,9 @@ export class PairingClient {
         catch (error) {
             if (signal?.aborted)
                 throw error;
+            if (error instanceof TeamClawsError &&
+                !["network_error", "network_timeout"].includes(error.code))
+                throw error;
             this.output.pairingStatus("unreachable", workspace);
             return "unreachable";
         }
@@ -74,50 +82,52 @@ export class PairingClient {
         let credential;
         try {
             credential = await this.poll(pending, signal);
+            const grant = await this.authorization.requireGrant();
+            if (credential.pairing_id !== credential.device_id ||
+                credential.server_id !== pending.server_id ||
+                credential.origin !== pending.target.origin ||
+                credential.requester_sub !== grant.sub ||
+                credential.authorization_id !== grant.authorization_id ||
+                credential.machine_jkt !== grant.machine_key.jkt)
+                throw verificationError();
             const initial = {
-                version: 1,
+                version: 2,
                 server_id: pending.server_id,
                 origin: pending.target.origin,
                 display_name: deviceName,
                 device_id: credential.device_id,
+                pairing_id: credential.pairing_id,
                 device_token: credential.device_token,
+                requester_sub: credential.requester_sub,
+                authorization_id: credential.authorization_id,
+                machine_jkt: credential.machine_jkt,
                 created_at: new Date(this.now()).toISOString(),
             };
-            await this.store.writeWorkspace(initial);
-            try {
-                const stored = await this.store.readWorkspace(pending.server_id);
-                if (!stored)
-                    throw verificationError();
-                const verification = await this.verify(pending, stored, signal);
-                const verified = {
-                    ...stored,
-                    display_name: verification.display_name,
-                };
-                await this.store.writeWorkspace(verified);
-                let snapshot;
-                let generatedAt;
-                if (Object.hasOwn(credential, "external_chat_capabilities")) {
-                    snapshot = null;
-                    generatedAt = null;
-                    try {
-                        const timestamp = credential.external_chat_capabilities_generated_at;
-                        if (typeof timestamp === "string" &&
-                            /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|\+00:00)$/.test(timestamp) &&
-                            Number.isFinite(Date.parse(timestamp))) {
-                            snapshot = parseCapabilityInventory(credential.external_chat_capabilities);
-                            generatedAt = timestamp;
-                        }
-                    }
-                    catch {
-                        // Optional inventory must not invalidate a successfully verified credential.
+            const verification = await this.verify(pending, initial, signal);
+            const verified = {
+                ...initial,
+                display_name: verification.display_name,
+            };
+            await this.store.writeWorkspace(verified);
+            let snapshot;
+            let generatedAt;
+            if (Object.hasOwn(credential, "external_chat_capabilities")) {
+                snapshot = null;
+                generatedAt = null;
+                try {
+                    const timestamp = credential.external_chat_capabilities_generated_at;
+                    if (typeof timestamp === "string" &&
+                        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|\+00:00)$/.test(timestamp) &&
+                        Number.isFinite(Date.parse(timestamp))) {
+                        snapshot = parseCapabilityInventory(credential.external_chat_capabilities);
+                        generatedAt = timestamp;
                     }
                 }
-                this.output.pairingComplete(pending.server_id, pending.target.origin, verification.display_name, verification.external_chat_handoff, snapshot, generatedAt);
-            }
-            catch (error) {
-                await this.store.removeWorkspace(pending.server_id);
-                throw error;
+                catch {
+                    // Optional inventory must not invalidate a successfully verified credential.
+                }
             }
+            this.output.pairingComplete(pending.server_id, pending.target.origin, verification.display_name, verification.external_chat_handoff, snapshot, generatedAt);
         }
         catch (error) {
             if (signal?.aborted) {
@@ -173,10 +183,8 @@ export class PairingClient {
             throw errorFromResponse(response, "cancel_failed");
     }
     async verify(pending, credential, signal) {
-        const response = await requestJson(this.fetcher, directTargetUrl(pending.target, pending.target.credential_verification_path), {
-            headers: {
-                Authorization: `Bearer ${credential.device_id}:${credential.device_token}`,
-            },
+        const url = directTargetUrl(pending.target, pending.target.credential_verification_path);
+        const response = await requestTargetJson(this.fetcher, this.authorization, url, credential, {
             ...(signal ? { signal } : {}),
         });
         if (response.status < 200 || response.status >= 300)

package/dist/shell.js

@@ -2,18 +2,17 @@ import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { Readable } from "node:stream";
 import { TeamClawsError } from "./errors.js";
-import { errorFromResponse, requestJson } from "./http.js";
+import { errorFromResponse } from "./http.js";
+import { requestTargetJson } from "./target-authorization.js";
 import { isObject } from "./validation.js";
-export async function runShell(store, fetcher, target, command, signal) {
+export async function runShell(store, fetcher, target, command, authorization, signal) {
     const credential = await store.findWorkspace(target);
     if (!credential) {
         throw new TeamClawsError("re_pair_required", "No saved pairing was found for this workspace. Pair it first.", { exitCode: 3 });
     }
-    const response = await requestJson(fetcher, `${credential.origin}/teamclaws-admin/api/shell/`, {
+    const url = `${credential.origin}/teamclaws-admin/api/shell/`;
+    const response = await requestTargetJson(fetcher, authorization, url, credential, {
         method: "POST",
-        headers: {
-            Authorization: `Bearer ${credential.device_id}:${credential.device_token}`,
-        },
         textBody: command,
         timeoutMs: null,
         responseLimitBytes: null,

package/dist/storage.js

@@ -5,6 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { TeamClawsError } from "./errors.js";
+import { parseDurableAuthorization, } from "./target-authorization.js";
 import { isObject, requireHttpsUrl, requireInteger, normalizeUuid, parseLoginCredential, parseStatusWorkspaceCredential, parseWorkspaceCredential, } from "./validation.js";
 const execFile = promisify(execFileCallback);
 const SYSTEM_SID = "S-1-5-18";
@@ -13,11 +14,13 @@ const UUID_CREDENTIAL_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0
 export class CredentialStore {
     root;
     loginPath;
+    authorizationPath;
     workspaceDirectory;
     platform;
     constructor(options = {}) {
         this.root = options.root ?? defaultRoot();
         this.loginPath = join(this.root, "cli-auth.json");
+        this.authorizationPath = join(this.root, "cli-authorization.json");
         this.workspaceDirectory = join(this.root, "clawgate-devices");
         this.platform = options.platform ?? process.platform;
     }
@@ -34,6 +37,19 @@ export class CredentialStore {
                 throw storageError();
         });
     }
+    async readAuthorization() {
+        const value = await this.readJsonIfPresent(this.authorizationPath);
+        return value === undefined ? undefined : parseDurableAuthorization(value);
+    }
+    async writeAuthorization(grant) {
+        await this.writePrivateJson(this.authorizationPath, parseDurableAuthorization(grant));
+    }
+    async removeAuthorization() {
+        await unlink(this.authorizationPath).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw storageError();
+        });
+    }
     workspacePath(serverId) {
         return join(this.workspaceDirectory, `${normalizeUuid(serverId)}.json`);
     }

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.4",
+  "version": "2.0.1",
   "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

@@ -9,6 +9,13 @@ For install-and-connect requests, follow
 [teamclaws-onboard](../teamclaws-onboard/SKILL.md) for the conversation sequence.
 A status-only request runs only `teamclaws auth status --json` and stops.
 
+Before starting browser login, explain that the user will sign this computer's
+TeamClaws command-line client into their TeamClaws account through the browser.
+This connects the client to their account; workspace selection and browser
+pairing approval come next when they are connecting a workspace. If onboarding
+already explained the process, use a short transition into this step. Give the
+approval link with that context, never as an unexplained authorization request.
+
 Use the official executable:
 
 ```text
@@ -16,22 +23,31 @@ 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
 next owner-facing message must link `login_browser_required.url` with the label
 **Sign in to TeamClaws** and include `account_guidance`. Keep the command running
-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.
+while the user signs in; do not restart it while awaiting approval. Keep your
+turn active and use the execution tool's wait/read operation on the same process
+handle. Do not require an "I approved" or "done" message. If the execution
+environment requires yielding, use a supported automatic completion callback or
+wakeup that preserves the process; report a limitation if neither is possible.
+Confirm the returned account after `login_complete` and exit 0, then immediately
+resume the authorized onboarding or pairing task. Denial, expiry, cancellation,
+and failure end the attempt; report the result without automatically restarting.
 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.