@tinycloud/cli 1.0.0-beta.16 → 1.0.0-beta.18

package/README.md

@@ -8,7 +8,16 @@ Self-sovereign storage from the terminal. `tc` is the command-line interface for
 npm install -g @tinycloud/cli
 ```
 
-Requires Node.js >= 20.
+Requires Node.js >= 20. On Linux, `/usr/sbin/tc` (iproute2) can shadow this
+CLI; call it as `"$(npm prefix --global)/bin/tc"` when in doubt.
+
+## Agent skills
+
+The package ships the general `tc-cli` skill and its references in
+`skills/tc-cli`. See [skill installation](skills/tc-cli/INSTALL.md) for a
+pinned, cross-agent installation with OpenCode, Codex and Claude Code, and
+[authentication](skills/tc-cli/AUTH.md) for device login and relaying the
+approval code to the owner.
 
 ## Operations coverage
 
@@ -34,11 +43,17 @@ tc init
 # Authenticate via browser
 tc auth login
 
-# Authenticate on a remote/headless machine
-tc auth login --device
+# Authenticate on a remote/headless machine: the owner approves an explicit
+# manifest on their phone (URL + code printed to stderr). Use a new profile
+# name if it already exists; keep the user's existing profiles.
+tc init --name publisher --key-only
+tc --profile publisher auth login --device --manifest builtin:share-publishing
+
+# Same Share publishing scope, as a shortcut (on the dedicated profile)
+tc --profile publisher enable share
 
-# Enable only Share publishing authority
-tc enable share
+# Selected profile, owner, host and space (JSON; does not test access)
+tc context
 
 # Store and retrieve data
 tc kv put greeting "Hello, world"
@@ -64,8 +79,10 @@ tc delegation create --to did:pkh:eip155:1:0x...
 |---------|-------------|
 | `tc init` | Set up a profile and generate keys |
 | `tc auth login` | Authenticate via browser |
-| `tc auth login --device` | Authenticate with an OpenKey URL and user code |
-| `tc enable share` | Enable narrowly scoped Share publishing authority |
+| `tc auth login --device --manifest <file>` | Approve exactly a manifest's permissions on another device (phone) |
+| `tc auth login --manifest <file>` | Browser OpenKey login scoped to a manifest |
+| `tc enable share` | Device login with the built-in Share publishing manifest (use a dedicated profile) |
+| `tc context` | Show the selected profile, owner, host, space and session state |
 | `tc auth status` | Show authentication status |
 | `tc auth whoami` | Show current identity |
 | `tc kv get <key>` | Retrieve a value |

package/dist/index.js

@@ -21,7 +21,7 @@ var init_constants = __esm({
     CONFIG_DIR = tinycloudHomePath();
     PROFILES_DIR = profilesPath();
     CONFIG_FILE = tinycloudConfigPath();
-    DEFAULT_HOST = "https://node.tinycloud.xyz";
+    DEFAULT_HOST = "https://tee.node.tinycloud.xyz";
     DEFAULT_PROFILE = "default";
     ExitCode = {
       SUCCESS: 0,
@@ -94,6 +94,11 @@ function outputError(code3, message, hint) {
 function isInteractive() {
   return Boolean(process.stdout.isTTY);
 }
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
 var init_formatter = __esm({
   "src/output/formatter.ts"() {
     "use strict";
@@ -104,6 +109,7 @@ var init_formatter = __esm({
 // src/output/errors.ts
 import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
+import { ProfileLockTimeoutError } from "@tinycloud/operations/state";
 function setActiveProfileName(name) {
   activeProfileName = name;
 }
@@ -121,6 +127,14 @@ function wrapError(error) {
     );
   }
   if (error instanceof CLIError) return error;
+  if (error instanceof ProfileLockTimeoutError) {
+    return new CLIError(
+      "PROFILE_LOCK_TIMEOUT",
+      `${message} Another tc or MCP process held this profile's lock, so the change that needed it was not written.`,
+      ExitCode.ERROR,
+      { hint: "Wait for the other command to finish and retry. A crashed process's lock is reclaimed automatically after 30 s." }
+    );
+  }
   if (message.includes("Not signed in") || message.includes("AUTH_EXPIRED") || message.includes("Session expired")) {
     return new CLIError("AUTH_REQUIRED", message, ExitCode.AUTH_REQUIRED);
   }
@@ -244,9 +258,9 @@ async function readJson(filePath) {
 async function writeJson(filePath, data) {
   const directory = dirname(filePath);
   const tempPath = join2(directory, `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
-  await mkdir(directory, { recursive: true });
+  await mkdir(directory, { recursive: true, mode: PRIVATE_DIR_MODE });
   try {
-    await writeFile(tempPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    await writeFile(tempPath, JSON.stringify(data, null, 2) + "\n", { encoding: "utf-8", mode: PRIVATE_FILE_MODE });
     await rename(tempPath, filePath);
   } catch (err) {
     await rm(tempPath, { force: true }).catch(() => void 0);
@@ -265,7 +279,7 @@ async function fileExists(filePath) {
   }
 }
 async function ensureDir(dirPath) {
-  await mkdir(dirPath, { recursive: true });
+  await mkdir(dirPath, { recursive: true, mode: PRIVATE_DIR_MODE });
 }
 async function removeDir(dirPath) {
   await rm(dirPath, { recursive: true, force: true });
@@ -281,9 +295,12 @@ async function listDirs(dirPath) {
     throw err;
   }
 }
+var PRIVATE_FILE_MODE, PRIVATE_DIR_MODE;
 var init_storage = __esm({
   "src/config/storage.ts"() {
     "use strict";
+    PRIVATE_FILE_MODE = 384;
+    PRIVATE_DIR_MODE = 448;
   }
 });
 
@@ -419,17 +436,14 @@ function profileLocalNodeIdentityStore(profileName) {
       return profile?.pinnedLocalNodeDids?.[url];
     },
     set: async (url, nodeDid) => {
-      const profile = await ProfileManager.getProfile(profileName).catch(
-        () => null
-      );
-      if (!profile) return;
-      await ProfileManager.setProfile(profileName, {
+      if (!await ProfileManager.profileExists(profileName)) return;
+      await ProfileManager.updateProfile(profileName, (profile) => ({
         ...profile,
         pinnedLocalNodeDids: {
           ...profile.pinnedLocalNodeDids,
           [url]: nodeDid
         }
-      });
+      }));
     }
   };
 }
@@ -524,10 +538,12 @@ var init_host = __esm({
 });
 
 // src/config/profiles.ts
+import { chmod, rm as rm2 } from "fs/promises";
 import { join as join3 } from "path";
 import {
   readSession,
   removeSession,
+  withProfileLock,
   writeSession
 } from "@tinycloud/operations/state";
 var ProfileManager;
@@ -540,11 +556,41 @@ var init_profiles = __esm({
     ProfileManager = class _ProfileManager {
       // ── Initialization ──────────────────────────────────────────────────
       /**
-       * Creates ~/.tinycloud/ and ~/.tinycloud/profiles/ if they don't exist.
+       * Runs `action` holding the profile's store lock (shared with operations
+       * and MCP). Reentrant, so the writers below can be called inside it; hold
+       * it around a whole read-modify-write, not just each write.
+       */
+      static async withLock(name, action, options) {
+        return withProfileLock(name, action, options);
+      }
+      /**
+       * Read-modify-write of profile.json under the profile lock, so concurrent
+       * updates (another command, a login commit) are never erased.
+       */
+      static async updateProfile(name, update) {
+        return _ProfileManager.withLock(name, async () => {
+          const next = update(await _ProfileManager.getProfile(name));
+          await _ProfileManager.setProfile(name, next);
+          return next;
+        });
+      }
+      /**
+       * Creates ~/.tinycloud/ and ~/.tinycloud/profiles/ if they don't exist and
+       * (re)sets both to 0700: older releases created them 0775.
        */
       static async ensureConfigDir() {
-        await ensureDir(CONFIG_DIR);
-        await ensureDir(PROFILES_DIR);
+        for (const directory of [CONFIG_DIR, PROFILES_DIR]) {
+          await ensureDir(directory);
+          await chmod(directory, PRIVATE_DIR_MODE);
+        }
+      }
+      /** Owner-only profile directory (0700), created or tightened before any write into it. */
+      static async ensureProfileDir(name) {
+        await _ProfileManager.ensureConfigDir();
+        const profileDir = join3(PROFILES_DIR, name);
+        await ensureDir(profileDir);
+        await chmod(profileDir, PRIVATE_DIR_MODE);
+        return profileDir;
       }
       // ── Global config ───────────────────────────────────────────────────
       /**
@@ -581,12 +627,17 @@ var init_profiles = __esm({
         return profile;
       }
       /**
-       * Saves a profile config, creating the profile directory if needed.
+       * Saves a profile config under the profile lock, creating the profile
+       * directory if needed. Use `updateProfile` to change an existing profile.
        */
       static async setProfile(name, data) {
-        const profileDir = join3(PROFILES_DIR, name);
-        await ensureDir(profileDir);
-        await writeJson(join3(profileDir, "profile.json"), data);
+        await _ProfileManager.withLock(name, async () => {
+          await writeJson(join3(await _ProfileManager.ensureProfileDir(name), "profile.json"), data);
+        });
+      }
+      /** Removes profile.json under the profile lock (rollback of a profile a failed login created). */
+      static async removeProfileConfig(name) {
+        await _ProfileManager.withLock(name, () => rm2(join3(PROFILES_DIR, name, "profile.json"), { force: true }));
       }
       /**
        * Returns true if a profile directory exists.
@@ -622,13 +673,15 @@ var init_profiles = __esm({
       static async getKey(name) {
         return readJson(join3(PROFILES_DIR, name, "key.json"));
       }
-      /**
-       * Saves a JWK key for a profile.
-       */
+      /** Saves a JWK key under the profile lock (0600, in an owner-only profile directory). */
       static async setKey(name, jwk) {
-        const profileDir = join3(PROFILES_DIR, name);
-        await ensureDir(profileDir);
-        await writeJson(join3(profileDir, "key.json"), jwk);
+        await _ProfileManager.withLock(name, async () => {
+          await writeJson(join3(await _ProfileManager.ensureProfileDir(name), "key.json"), jwk);
+        });
+      }
+      /** Removes key.json under the profile lock (rollback of a key a failed login created). */
+      static async removeKey(name) {
+        await _ProfileManager.withLock(name, () => rm2(join3(PROFILES_DIR, name, "key.json"), { force: true }));
       }
       // ── Session management ──────────────────────────────────────────────
       /**
@@ -651,11 +704,13 @@ var init_profiles = __esm({
       }
       // ── Cache management ────────────────────────────────────────────────
       /**
-       * Returns the path to the profile's cache directory, creating it if needed.
+       * Returns the profile's cache directory (share history lives here),
+       * created or tightened to 0700.
        */
       static async getCacheDir(name) {
-        const cacheDir = join3(PROFILES_DIR, name, "cache");
+        const cacheDir = join3(await _ProfileManager.ensureProfileDir(name), "cache");
         await ensureDir(cacheDir);
+        await chmod(cacheDir, PRIVATE_DIR_MODE);
         return cacheDir;
       }
       // ── Resolution helpers ──────────────────────────────────────────────
@@ -5535,8 +5590,15 @@ var init_zod = __esm({
   }
 });
 
+// src/share/publishing-manifest.ts
+var init_publishing_manifest = __esm({
+  "src/share/publishing-manifest.ts"() {
+    "use strict";
+  }
+});
+
 // src/lib/permissions.ts
-import { appendFile, readFile as readFile3 } from "fs/promises";
+import { appendFile, chmod as chmod2, readFile as readFile3 } from "fs/promises";
 import { join as join5 } from "path";
 import {
   buildPermissionRequestArtifact,
@@ -5549,7 +5611,7 @@ import {
   readAdditionalDelegations,
   readAuthRequests,
   upsertProfileRecord,
-  withProfileLock,
+  withProfileLock as withProfileLock2,
   writeJsonAtomic
 } from "@tinycloud/operations/state";
 async function loadAdditionalDelegations(profile) {
@@ -5579,6 +5641,7 @@ var init_permissions = __esm({
     init_errors();
     init_constants();
     init_space();
+    init_publishing_manifest();
     init_types();
   }
 });
@@ -5694,17 +5757,19 @@ async function bootstrapDelegatedSession(ctx, delegation) {
   }
   const key = await ProfileManager.getKey(ctx.profile);
   const jwk = signerJwkForProfile(ctx.profile, void 0, key);
-  await ProfileManager.setSession(ctx.profile, {
-    delegationHeader: delegation.delegationHeader,
-    delegationCid: delegation.cid,
-    spaceId: delegation.spaceId,
-    jwk,
-    verificationMethod: sessionDid
-  });
-  await ProfileManager.setProfile(ctx.profile, {
-    ...profile,
-    sessionDid,
-    spaceId: delegation.spaceId
+  await ProfileManager.withLock(ctx.profile, async () => {
+    await ProfileManager.setSession(ctx.profile, {
+      delegationHeader: delegation.delegationHeader,
+      delegationCid: delegation.cid,
+      spaceId: delegation.spaceId,
+      jwk,
+      verificationMethod: sessionDid
+    });
+    await ProfileManager.updateProfile(ctx.profile, (current) => ({
+      ...current,
+      sessionDid,
+      spaceId: delegation.spaceId
+    }));
   });
   return createSDKInstance(ctx);
 }
@@ -14991,6 +15056,7 @@ function parseDuration(input) {
 }
 
 // src/commands/share.ts
+init_formatter();
 init_errors();
 
 // src/share/output.ts
@@ -15030,7 +15096,7 @@ function receiveJson(result, path) {
 
 // src/share/io.ts
 import { constants } from "fs";
-import { lstat, mkdir as mkdir2, mkdtemp, open as open2, readFile as readFile2, realpath, stat as stat2, link, rename as rename2, rm as rm2, unlink } from "fs/promises";
+import { lstat, mkdir as mkdir2, mkdtemp, open as open2, readFile as readFile2, realpath, stat as stat2, link, rename as rename2, rm as rm3, unlink } from "fs/promises";
 import { randomBytes as randomBytes2 } from "crypto";
 import { basename as basename2, join as join4, resolve, sep } from "path";
 var MAX_SHARE_STDIN_BYTES = 100 * 1024 * 1024;
@@ -15144,7 +15210,7 @@ async function writeShareOutput(directory, filename, bytes, force) {
       if (temporaryPath !== void 0) await unlink(temporaryPath);
     } catch {
     }
-    await rm2(stagingDirectory, { recursive: true, force: true });
+    await rm3(stagingDirectory, { recursive: true, force: true });
     await directoryHandle.close();
   }
   return join4(outputDirectory, safeName);
@@ -15187,23 +15253,24 @@ function shareCliError(error) {
     const profileName = "profileName" in failure ? failure.profileName : void 0;
     const localKey = "localKey" in failure && failure.localKey === true;
     const profileHint = profileName === void 0 ? "" : `--profile ${profileName} `;
-    const loginHint = `tc ${profileHint}auth login${localKey ? " --method local" : ""}`;
+    const loginHint = localKey ? `\`tc ${profileHint}auth login --method local\`` : `\`tc ${profileHint}auth login --device --manifest builtin:share-publishing\` (or \`tc ${profileHint}enable share\`)`;
     if (failure.kind === "owner-space-unresolved") {
-      return new CLIError("AUTH_REQUIRED", `a valid signed TinyCloud session is required; run \`${loginHint}\``, 3);
+      return new CLIError("AUTH_REQUIRED", `a valid signed TinyCloud session is required; run ${loginHint}`, 3);
     }
     if (failure.kind === "scope-denied") {
       const requiredAction = failure.requiredAction === void 0 ? "" : ` (${failure.requiredAction})`;
-      return new CLIError("PERMISSION_DENIED", `the session lacks ${failure.capability} authority${requiredAction}; renew it with \`${loginHint}\` using the required capability`, 5);
+      const renew = localKey ? `renew it with ${loginHint} using the required capability` : `verify the session includes the builtin:share-publishing scope; if it does not, request it with ${loginHint}`;
+      return new CLIError("PERMISSION_DENIED", `the session lacks ${failure.capability} authority${requiredAction}; ${renew}`, 5);
     }
     if (failure.kind === "lifetime-exceeds-session") {
       const expiresAt = failure.sessionExpiresAt.toISOString();
       if (failure.reason === "session-too-close") {
-        return new CLIError("AUTH_REQUIRED", `the signed session expires too soon (${expiresAt}); log in again with \`${loginHint}\``, 3);
+        return new CLIError("AUTH_REQUIRED", `the signed session expires too soon (${expiresAt}); log in again with ${loginHint}`, 3);
       }
       if (failure.reason === "below-minimum") {
         return new CLIError("SESSION_LIFETIME_EXCEEDED", "share expiry must be at least 60 seconds from now; use a longer --expires value", 2);
       }
-      return new CLIError("SESSION_LIFETIME_EXCEEDED", `requested share lifetime exceeds session expiry ${expiresAt}; use a shorter --expires value or renew the session with \`${loginHint}\``, 2);
+      return new CLIError("SESSION_LIFETIME_EXCEEDED", `requested share lifetime exceeds session expiry ${expiresAt}; use a shorter --expires value or renew the session with ${loginHint}`, 2);
     }
     if (failure.kind === "origin-mismatch") {
       return new CLIError("ORIGIN_MISMATCH", "share origin does not match the configured service", 2);
@@ -15217,6 +15284,13 @@ function shareCliError(error) {
     if (failure.kind === "registry-rejected") {
       return new CLIError("REGISTRY_REJECTED", "the TinyCloud location registry rejected this session's location record, so nothing was shared; retrying will not help. Log in again, and report the problem if it persists", 6);
     }
+    if (failure.kind === "storage-quota-exceeded") {
+      const sizes = failure.usedBytes === void 0 || failure.limitBytes === void 0 ? "" : ` (${formatBytes(failure.usedBytes)} used of ${formatBytes(failure.limitBytes)} limit)`;
+      return new CLIError("STORAGE_QUOTA_EXCEEDED", `storage quota exceeded${sizes}; nothing was shared`, 4);
+    }
+    if (failure.kind === "upload-failed") {
+      return new CLIError("UPLOAD_FAILED", "share source upload failed; nothing was shared", 4);
+    }
   }
   if (error instanceof ShareNotifyError) {
     return new CLIError("INVALID_ARGUMENT", error.message, 2);
@@ -16836,7 +16910,26 @@ function requiredKvAction(meta) {
   const action = meta.requiredAction;
   return action === "tinycloud.kv/put" || action === "tinycloud.kv/get" ? action : void 0;
 }
+function isByteCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function throwKvUploadFailure(error) {
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "STORAGE_QUOTA_EXCEEDED") {
+    const meta = "meta" in error && typeof error.meta === "object" && error.meta !== null ? error.meta : {};
+    const { usedBytes, limitBytes } = meta;
+    throw new SharePublishAuthorityError(isByteCount(usedBytes) && isByteCount(limitBytes) ? { kind: "storage-quota-exceeded", usedBytes, limitBytes } : { kind: "storage-quota-exceeded" });
+  }
+  throw new SharePublishAuthorityError({ kind: "upload-failed" });
+}
 var DEFAULT_SHARE_ORIGIN = "https://share.tinycloud.xyz";
+var URI_SAFE_FILENAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function safeStorageFilename(filename) {
+  if (URI_SAFE_FILENAME.test(filename) && !filename.includes("..")) return filename;
+  const dot = filename.lastIndexOf(".");
+  const extension = dot >= 0 && /^[A-Za-z0-9]{1,16}$/.test(filename.slice(dot + 1)) ? filename.slice(dot + 1) : "";
+  const stem = (extension === "" ? filename : filename.slice(0, dot)).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(extension === "" ? /[^A-Za-z0-9_-]+/g : /[^A-Za-z0-9._-]+/g, "-").replace(/\.{2,}/g, ".").replace(/-{2,}/g, "-").slice(0, 100).replace(/^[^A-Za-z0-9]+|[-.]+$/g, "");
+  return `${stem === "" ? "share" : stem}${extension === "" ? "" : `.${extension}`}`;
+}
 function createEncryptedSessionHistory() {
   const records = /* @__PURE__ */ new Map();
   let keyPromise;
@@ -17068,7 +17161,7 @@ function createShareAuthorityAdapters(input = {}) {
     if (targetInput.target.kind === "bearer") {
       if (resourceKind !== "exact" || files.length !== 1) throw new Error("native bearer publication requires one exact source file");
       const file2 = files[0];
-      const resourcePath2 = `xyz.tinycloud.share/shares/${shareId}/${targetInput.filename}`;
+      const resourcePath2 = `xyz.tinycloud.share/shares/${shareId}/${safeStorageFilename(targetInput.filename)}`;
       const written = await node.kvForSpace(ownerSpaceId).put(resourcePath2, file2.bytes.slice(), {
         contentType: targetInput.mediaType ?? file2.mediaType ?? "application/octet-stream"
       });
@@ -17084,7 +17177,7 @@ function createShareAuthorityAdapters(input = {}) {
             profileName: activeProfileName2
           });
         }
-        throw new Error("native bearer source upload failed");
+        throwKvUploadFailure(written.error);
       }
       let native;
       try {
@@ -17132,7 +17225,7 @@ function createShareAuthorityAdapters(input = {}) {
     }
     if (resourceKind !== "exact" || files.length !== 1) throw new Error("addressed publication requires a single exact source file");
     const file = files[0];
-    const resourcePath = `shares/${shareId}/${targetInput.filename}`;
+    const resourcePath = `shares/${shareId}/${safeStorageFilename(targetInput.filename)}`;
     const byteLength = file.bytes.byteLength;
     if (!Number.isSafeInteger(byteLength) || byteLength > 100 * 1024 * 1024) throw new Error("addressed publication exceeds the combined byte limit");
     const mediaType = targetInput.mediaType ?? file.mediaType ?? "application/octet-stream";
@@ -17167,7 +17260,7 @@ function createShareAuthorityAdapters(input = {}) {
           profileName: activeProfileName2
         });
       }
-      throw new Error("addressed source upload failed");
+      throwKvUploadFailure(stored.error);
     }
     const contentSource = {
       shareId,