cesiumcloud 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CesiumCloud
+
+Secure cloud storage CLI and JavaScript SDK. Upload, download, and manage files from your terminal or applications.
+
+## Install
+
+Requires Node.js 22 or newer.
+
+    npm install -g cesiumcloud
+
+If Windows PowerShell does not recognize the command after installation, open a new terminal or add the npm global command directory to PATH.
+
+## Commands
+
+    cesiumcloud authenticate
+    cesiumcloud upload "E:\downloads\dogimages.zip"
+    cesiumcloud upload "E:\my-backup-folder"
+    cesiumcloud download "E:\empty-restore-directory"
+    cesiumcloud whoami
+    cesiumcloud logout
+
+Run `cesiumcloud authenticate` to approve this computer through your CesiumCloud account. Subsequent commands work without manually entering an API key.
+
+Interrupted uploads can resume. The `download` command currently restores account backups to the specified directory; selective file download is not yet supported.
+
+## JavaScript SDK
+
+    const { CesiumCloudClient } = require("cesiumcloud");
+    const client = new CesiumCloudClient();
+    await client.authenticate({
+      onChallenge: ({ verificationUri, userCode }) => {
+        console.log("Open", verificationUri, "and enter", userCode);
+      }
+    });
+    await client.uploadFile("E:\\downloads\\dogimages.zip");
+    await client.uploadFolder("E:\\my-backup-folder");
+
+For device access management, sign in at https://cloud.cesiummc.space/device/manage.html.
+
+## Security
+
+Authentication creates a device-specific access credential, stored on the local computer. Treat stored credentials as sensitive. Use the CesiumCloud dashboard to revoke devices when needed. The `logout` command clears the local credential but does not revoke server-side access.
+
+## Support
+
+Website: https://cloud.cesiummc.space/
+Documentation: https://api.cesiummc.space/docs
+
+## Existing TenCloud accounts
+
+CesiumCloud uses the existing API at https://api.cesiummc.space and reads the legacy ~/.tencloud/credentials.json token so existing installations and API keys continue working. The legacy TenCloud package remains available for compatibility.

package/bin/cesiumcloud.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+"use strict";
+/* CesiumCloud CLI v28. Node >=22, dependency-free. */
+const fs=require("node:fs"),fsp=require("node:fs/promises"),path=require("node:path"),os=require("node:os");
+const API=(process.env.CESIUMCLOUD_API_URL||process.env.TENCLOUD_API_URL)||"https://api.cesiummc.space";
+const configDir=process.env.TENCLOUD_CONFIG_DIR||path.join(os.homedir(),".tencloud");
+const credPath=path.join(configDir,"credentials.json");
+const wait=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+function usage(){
+ console.log("CesiumCloud CLI\n\n  cesiumcloud authenticate    Sign in using the CesiumCloud website\n  cesiumcloud upload PATH     Upload a file or folder to CesiumCloud\n  cesiumcloud download DIR    Restore your backups to a directory\n  cesiumcloud whoami          Show your account\n  cesiumcloud logout          Remove locally saved credentials\n\nRequires Node.js 22+.");
+}
+async function request(uri,{method="GET",body,token}={}){
+ const res=await fetch(API+uri,{method,headers:{accept:"application/json",...(body?{"content-type":"application/json"}:{}),...(token?{authorization:"Bearer "+token}:{})},body:body?JSON.stringify(body):undefined,signal:AbortSignal.timeout(40000),cache:"no-store"});
+ const data=await res.json().catch(()=>({error:"Invalid server response"}));
+ return {res,data};
+}
+async function credential(){
+ if(process.env.CESIUMCLOUD_API_KEY||process.env.TENCLOUD_API_KEY)return process.env.CESIUMCLOUD_API_KEY||process.env.TENCLOUD_API_KEY;
+ let raw;
+ try{raw=JSON.parse(await fsp.readFile(credPath,"utf8"));}catch{return "";}
+ return raw.api===API&&/^tc_live_[a-f0-9]{64}$/.test(raw.token||"")?raw.token:"";
+}
+async function save(token){
+ await fsp.mkdir(configDir,{recursive:true,mode:0o700});
+ const temp=credPath+"."+process.pid+".tmp";
+ await fsp.writeFile(temp,JSON.stringify({api:API,token},null,2),{mode:0o600,flag:"wx"});
+ await fsp.rename(temp,credPath);
+ if(process.platform!=="win32")await fsp.chmod(credPath,0o600);
+}
+async function authenticate(){
+ const {res,data}=await request("/v1/device/start",{method:"POST",body:{label:os.hostname().slice(0,40)||"CesiumCloud CLI"}});
+ if(!res.ok)throw Error("Unable to begin authorization: "+(data.error||res.status));
+ console.log("\nOpen this URL in your browser:\n  "+data.verification_uri);
+ console.log("\nEnter this device code:\n  "+data.user_code);
+ console.log("\nSign into your CesiumCloud account and approve the request.");
+ console.log("Checking for approval (press Ctrl+C to cancel)...\n");
+ const expires=Date.now()+data.expires_in*1000;
+ const interval=Math.max(7000,(data.interval||7)*1000);
+ while(Date.now()<expires){
+  await wait(interval);
+  const answer=await request("/v1/device/token",{method:"POST",body:{device_code:data.device_code}});
+  if(answer.res.ok&&answer.data.access_token){
+   const check=await request("/v1/me",{token:answer.data.access_token});
+   if(!check.res.ok)throw Error("CesiumCloud rejected the authorized credential.");
+   await save(answer.data.access_token);
+   console.log("Authenticated as "+check.data.email+".");
+   return;
+  }
+  if(["authorization_pending","slow_down"].includes(answer.data.error))continue;
+  if(["access_denied","expired_token"].includes(answer.data.error))throw Error("Authorization "+answer.data.error.replace("_"," ")+".");
+  throw Error("Authorization check failed: "+(answer.data.error||answer.res.status));
+ }
+ throw Error("Authorization expired; run cesiumcloud authenticate again.");
+}
+async function requireToken(){
+ const t=await credential();
+ if(!t)throw Error("Not authenticated. Run: cesiumcloud authenticate");
+ return t;
+}
+async function cli(){
+ if(Number(process.versions.node.split(".")[0])<22)throw Error("Node.js 22+ required.");
+ const [cmd,target]=process.argv.slice(2);
+ if(["-h","--help","help",undefined].includes(cmd)){usage();return;}
+ if(cmd==="authenticate"||cmd==="login"){await authenticate();return;}
+ if(cmd==="logout"){
+  if(process.env.TENCLOUD_API_KEY)console.log("TENCLOUD_API_KEY is set; unset it separately.");
+  await fsp.rm(credPath,{force:true});
+  console.log("Saved local credential removed. Revoke server access at the CesiumCloud device management page.");
+  return;
+ }
+ if(cmd==="whoami"){
+  const r=await request("/v1/me",{token:await requireToken()});
+  if(!r.res.ok)throw Error("Authentication failed. Run: cesiumcloud authenticate");
+  console.log(r.data.email+" ("+r.data.access+")");return;
+ }
+ if(["upload","download"].includes(cmd)){
+  if(!target)throw Error("A path is required. Example: cesiumcloud upload \"E:\\downloads\\dogimages.zip\"");
+  process.env.TENCLOUD_API_KEY=await requireToken();
+  const service=require("../lib/backup.cjs");
+  if(cmd==="upload")await service.backup(path.resolve(target));
+  else await service.restore(path.resolve(target));
+  return;
+ }
+ throw Error("Unknown command: "+cmd+". Run cesiumcloud --help.");
+}
+cli().catch(e=>{console.error("CesiumCloud error: "+e.message);process.exitCode=1;});

package/lib/backup.cjs

@@ -0,0 +1,316 @@
+"use strict";
+/* TenCloud Backup Client v27
+ * Mandatory packed backups, direct-to-Google upload, restart-safe checkpoints.
+ * Checkpoints contain pack IDs/fingerprints only (no API key or upload URL).
+ * Usage: TENCLOUD_API_KEY=... node TenCloud_BackupClient_v27.cjs backup PATH
+ *        TENCLOUD_API_KEY=... node TenCloud_BackupClient_v27.cjs restore EMPTY_PATH
+ */
+const fs=require("node:fs"),fsp=require("node:fs/promises"),path=require("node:path");
+const os=require("node:os"),crypto=require("node:crypto");
+const {plans,readSlice,parseHeader,parseManifest}=require("./packformat.cjs");
+const API=(process.env.CESIUMCLOUD_API_URL||process.env.TENCLOUD_API_URL)||"https://api.cesiummc.space";
+const TOKEN=process.env.CESIUMCLOUD_API_KEY||process.env.TENCLOUD_API_KEY||"";
+const CHUNK=8*1024*1024,MAX_RETRIES=5;
+const delay=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+const sha=x=>crypto.createHash("sha256").update(x).digest("hex");
+const uuid=()=>crypto.randomUUID();
+function fmt(n){return n>=1073741824?(n/1073741824).toFixed(2)+" GiB":n>=1048576?(n/1048576).toFixed(2)+" MiB":n+" B";}
+async function api(resource,{method="GET",body}={}){
+ const res=await fetch(API+resource,{method,
+  headers:{Authorization:"Bearer "+TOKEN,...(body?{"content-type":"application/json"}:{})},
+  body:body?JSON.stringify(body):undefined,
+  signal:AbortSignal.timeout(40000),cache:"no-store"});
+ const raw=await res.text();let data;
+ try{data=JSON.parse(raw);}catch{throw Error("Worker returned invalid JSON (HTTP "+res.status+")");}
+ if(!res.ok)throw Error("Worker HTTP "+res.status+": "+JSON.stringify(data?.error||data).slice(0,220));
+ return data;
+}
+async function queryGoogle(session,total){
+ const response=await fetch(session,{method:"PUT",headers:{"Content-Range":"bytes */"+total},signal:AbortSignal.timeout(40000)});
+ if(response.status===308){
+  const range=response.headers.get("range")||"";
+  const match=range.match(/(?:bytes=)?0-(\d+)$/);
+  return {offset:match?Number(match[1])+1:0};
+ }
+ if(response.status===200||response.status===201)
+  return {offset:total,done:await response.json()};
+ if(response.status===404||response.status===410)throw Error("Google upload session expired; checkpoint retained for recovery");
+ throw Error("Google resumable status HTTP "+response.status);
+}
+async function sendDirect(plan,root,session,{resume=false,onAcknowledged}={}){
+ let offset=0,done=null,attempt=0;
+ if(resume){
+  const status=await queryGoogle(session,plan.totalBytes);
+  if(status.done)return status.done;
+  offset=status.offset;
+  console.log("Resuming direct Google Drive pack at byte "+offset+" of "+plan.totalBytes);
+ }
+ if(offset<0||offset>plan.totalBytes||!Number.isSafeInteger(offset))throw Error("Invalid server upload offset");
+ while(offset<plan.totalBytes){
+  const n=Math.min(CHUNK,plan.totalBytes-offset);
+  // Never buffer more than the current 8 MiB upload chunk.
+  const data=await readSlice(root,plan,offset,n);
+  let response;
+  try{
+   response=await fetch(session,{method:"PUT",
+    headers:{"content-range":"bytes "+offset+"-"+(offset+n-1)+"/"+plan.totalBytes,
+      "content-type":"application/octet-stream","content-length":String(n)},
+    body:data,signal:AbortSignal.timeout(180000)});
+  }catch(e){
+   if(++attempt>MAX_RETRIES)throw Error("Google upload transport error: "+e.message);
+   await delay(attempt*1200);
+   const probe=await queryGoogle(session,plan.totalBytes);
+   if(probe.done)return probe.done;
+   offset=probe.offset;continue;
+  }
+  if(response.status===308){
+   const range=response.headers.get("range"),match=range?.match(/(?:bytes=)?0-(\d+)$/);
+   // A missing Range on a noninitial acknowledged chunk is unsafe.
+   const acknowledged=match?Number(match[1])+1:NaN;
+   if(!Number.isSafeInteger(acknowledged)||acknowledged<=offset||acknowledged>plan.totalBytes)
+    throw Error("Google resumable chunk acknowledgment was invalid");
+   offset=acknowledged;attempt=0;
+   if(onAcknowledged)await onAcknowledged(offset,plan.totalBytes);
+   continue;
+  }
+  if(response.ok){
+   done=await response.json();
+   if(!done?.id)throw Error("Completed Google upload did not return a file ID");
+   offset=plan.totalBytes;break;
+  }
+  if(![403,408,429,500,502,503,504].includes(response.status))
+   throw Error("Google rejected upload chunk: HTTP "+response.status);
+  if(++attempt>MAX_RETRIES)throw Error("Too many Google upload retries (HTTP "+response.status+")");
+  await delay(attempt*1200);
+  const probe=await queryGoogle(session,plan.totalBytes);
+  if(probe.done)return probe.done;
+  offset=probe.offset;
+ }
+ if(!done?.id)throw Error("Google did not confirm completed upload");
+ return done;
+}
+function stateDirectory(){
+ return path.resolve(process.env.TENCLOUD_BACKUP_STATE_DIR||path.join(
+  process.env.LOCALAPPDATA||path.join(os.homedir(),".local","state"),"TenCloud","checkpoints"));
+}
+function stateFile(root,account,maxPackBytes){
+ const identifier=sha(JSON.stringify([path.resolve(root),account.toLowerCase(),maxPackBytes,API]));
+ return path.join(stateDirectory(),identifier+".json");
+}
+async function saveState(file,state){
+ const temp=file+"."+process.pid+".tmp";
+ await fsp.writeFile(temp,JSON.stringify(state,null,2),{mode:0o600,flag:"w"});
+ await fsp.rename(temp,file);
+}
+async function loadState(file){
+ try{
+  const data=JSON.parse(await fsp.readFile(file,"utf8"));
+  if(data.version!==2||!Array.isArray(data.completed)||!data.root||!data.account)
+   throw Error("Invalid saved checkpoint format");
+  return data;
+ }catch(e){if(e.code==="ENOENT")return null;throw e;}
+}
+function fingerprint(plan){
+ return sha(Buffer.concat([plan.header,Buffer.from(JSON.stringify(plan.entries.map(e=>[e.p,e.o,e.n,e.s,e.m])))]));
+}
+async function lockState(file){
+ const lock=file+".lock";
+ try{
+  const h=await fsp.open(lock,"wx",0o600);
+  await h.writeFile(JSON.stringify({pid:process.pid,time:Date.now()}));
+  return async()=>{await h.close();await fsp.unlink(lock).catch(()=>{});};
+ }catch(e){
+  if(e.code!=="EEXIST")throw e;
+  // Interrupted/crashed process: reclaim only if OS confirms its PID is gone.
+  let previous;
+  try{previous=JSON.parse(await fsp.readFile(lock,"utf8"));}catch{}
+  if(Number.isInteger(previous?.pid)&&previous.pid>0){
+   try{process.kill(previous.pid,0);}catch(err){
+    if(err.code==="ESRCH"){await fsp.unlink(lock).catch(()=>{});return lockState(file);}
+   }
+  }
+  throw Error("Another backup may be running, or a stale checkpoint lock exists: "+lock);
+ }
+}
+async function backup(folder,options={}){
+ if(!/^tc_live_[0-9a-f]{64}$/.test(TOKEN))throw Error("Set TENCLOUD_API_KEY");
+ const root=path.resolve(folder),stat=await fsp.stat(root);
+ if(!stat.isDirectory()&&!stat.isFile())throw Error("Backup source must be a regular file or directory");
+ const maxPackBytes=Number(process.env.TENCLOUD_TEST_PACK_BYTES||0)||64*1024*1024*1024;
+ const me=await api("/v1/me");
+ const account=String(me.email||"").toLowerCase();
+ if(!account)throw Error("Account identity unavailable");
+ await fsp.mkdir(stateDirectory(),{recursive:true,mode:0o700});
+ const file=stateFile(root,account,maxPackBytes),unlock=await lockState(file);
+ let currentPlan=0,packs=0,segments=0,bytes=0;
+ try{
+  let state=await loadState(file);
+  if(state&&(state.root!==root||state.account!==account||state.maxPackBytes!==maxPackBytes))
+   throw Error("Checkpoint does not match account, directory or pack size");
+  if(!state){
+   state={version:2,root,account,maxPackBytes,startedAt:Date.now(),completed:[],current:null};
+   await saveState(file,state);
+  }else console.log("Found interrupted backup checkpoint; verifying pack positions before resuming");
+  for await(const plan of plans(root,{maxPackBytes})){
+   const fp=fingerprint(plan),index=currentPlan++;
+   const recorded=state.completed[index];
+   if(recorded){
+    if(recorded.sequence!==index||recorded.fingerprint!==fp)
+     throw Error("Source contents changed since checkpoint (pack "+(index+1)+"). Refusing to mix snapshots.");
+    packs++;segments+=plan.entries.length;bytes+=plan.payloadBytes;
+    console.log("Skipping already committed pack "+(index+1));
+    continue;
+   }
+   if(state.current&&(state.current.sequence!==index||state.current.fingerprint!==fp))
+    throw Error("Source contents changed while a pack was unfinished. Checkpoint preserved at "+file);
+   if(!state.current){
+    state.current={sequence:index,fingerprint:fp,requestId:uuid(),packId:null,driveFileId:null};
+    await saveState(file,state);
+   }
+   const working=state.current;
+   let status=null;
+   if(working.packId){
+    status=await api("/v1/packs/"+working.packId);
+    if(status.sizeBytes!==plan.totalBytes||status.segments!==plan.entries.length)
+     throw Error("Server pack and local checkpoint differ; refusing to resume");
+    if(status.state==="ready"){
+     state.completed.push({sequence:index,fingerprint:fp,packId:working.packId});
+     state.current=null;await saveState(file,state);
+     packs++;segments+=plan.entries.length;bytes+=plan.payloadBytes;
+     continue;
+    }
+    if(status.state==="expired"||status.state==="failed"){
+     // A paused backup can outlive Google's resumable upload session.
+     // Preserve all committed packs; replace only this unfinished pack.
+     await api("/v1/packs/"+working.packId,{method:"DELETE"});
+     working.packId=null;working.driveFileId=null;
+     working.started=false;working.requestId=uuid();
+     await saveState(file,state);
+     console.log("Expired pack session replaced; previously committed packs kept");
+    }else if(status.state!=="uploading"||!status.uploadUrl)
+     throw Error("Upload session cannot resume ("+status.state+"). Checkpoint retained: "+file);
+   }
+   if(!working.packId){
+    const registered=await api("/v1/packs",{method:"POST",body:{
+     requestId:working.requestId,sizeBytes:plan.totalBytes,
+     sourceBytes:plan.payloadBytes,segments:plan.entries.length
+    }});
+    working.packId=registered.packId;
+    await saveState(file,state);
+    status=registered;
+    if(status.state==="ready"){
+     state.completed.push({sequence:index,fingerprint:fp,packId:working.packId});
+     state.current=null;await saveState(file,state);
+     packs++;segments+=plan.entries.length;bytes+=plan.payloadBytes;continue;
+    }
+   }
+   let driveFileId=working.driveFileId;
+   if(!driveFileId){
+    const resuming=!!working.started||!!options.forceGoogleStatusCheck;
+    if(!working.started){working.started=true;await saveState(file,state);}
+    const complete=await sendDirect(plan,root,status.uploadUrl,{
+     resume:resuming,onAcknowledged:options.onAcknowledged
+    });
+    driveFileId=complete.id;
+    working.driveFileId=driveFileId;
+    await saveState(file,state);
+   }
+   const confirmed=await api("/v1/packs/"+working.packId+"/commit",{
+    method:"POST",body:{driveFileId}
+   });
+   if(!confirmed.ok)throw Error("Pack commit not confirmed");
+   state.completed.push({sequence:index,fingerprint:fp,packId:working.packId});
+   state.current=null;
+   await saveState(file,state);
+   packs++;segments+=plan.entries.length;bytes+=plan.payloadBytes;
+   console.log("Committed pack "+(index+1)+": "+fmt(plan.payloadBytes)+" across "+plan.entries.length+" file segments");
+  }
+  if(state.completed.length!==currentPlan)
+   throw Error("Saved backup manifest mismatch; checkpoint retained");
+  await fsp.unlink(file);
+  console.log("BACKUP COMPLETE: "+packs+" packs, "+segments+" segments, "+fmt(bytes)+" source content");
+  return {packs,segments,sourceBytes:bytes,approxWorkerRequests:2*packs+1};
+ }catch(err){
+  // Preserve partial Google session and checkpoint; do NOT delete the pack.
+  console.error("Backup interrupted. State kept at "+file);
+  throw err;
+ }finally{await unlock();}
+}
+function safeTarget(root,relative){
+ if(typeof relative!=="string"||relative.includes("\\")||relative.includes("\0")||
+    relative.startsWith("/")||relative.split("/").some(s=>s===".."||s==="."||!s))
+  throw Error("Unsafe backup entry path");
+ const target=path.resolve(root,...relative.split("/"));
+ if(!target.startsWith(root+path.sep))throw Error("Restore path escapes root");
+ return target;
+}
+async function restore(destination){
+ if(!/^tc_live_[0-9a-f]{64}$/.test(TOKEN))throw Error("Set TENCLOUD_API_KEY");
+ const dir=path.resolve(destination);
+ await fsp.mkdir(dir,{recursive:true});
+ if((await fsp.readdir(dir)).length)throw Error("Restore destination must be empty");
+ const packs=[];let cursor=0;
+ while(true){
+  const suffix="?limit=200"+(cursor?"&before="+cursor:"");
+  const r=await api("/v1/packs"+suffix);
+  packs.push(...r.packs);
+  if(!r.nextBefore||r.packs.length<200)break;
+  cursor=r.nextBefore;
+ }
+ packs.sort((a,b)=>a.created_at-b.created_at||a.id.localeCompare(b.id));
+ let restored=0;
+ for(const [n,pack] of packs.entries()){
+  const resp=await fetch(API+"/v1/packs/"+pack.id+"/download",{
+   headers:{Authorization:"Bearer "+TOKEN},signal:AbortSignal.timeout(4*60*60*1000)});
+  if(!resp.ok||!resp.body)throw Error("Pack "+pack.id+" download HTTP "+resp.status);
+  const reader=resp.body[Symbol.asyncIterator]();let carry=Buffer.alloc(0);
+  async function take(size){
+   const parts=[];let got=0;
+   while(got<size){
+    if(carry.length){
+     const take=carry.subarray(0,Math.min(size-got,carry.length));
+     parts.push(take);carry=carry.subarray(take.length);got+=take.length;continue;
+    }
+    const item=await reader.next();if(item.done)throw Error("Unexpected end of packed backup");
+    carry=Buffer.from(item.value);
+   }
+   return Buffer.concat(parts,size);
+  }
+  const head=await take(16),h=parseHeader(head),idx=parseManifest(head,await take(h.zipLen));
+  let streamed=0;
+  for(const entry of idx.entries){
+   const target=safeTarget(dir,entry.p);
+   await fsp.mkdir(path.dirname(target),{recursive:true});
+   let handle;
+   try{handle=await fsp.open(target,"r+");}catch(e){if(e.code!=="ENOENT")throw e;handle=await fsp.open(target,"w+");}
+   try{
+    for(let offset=0;offset<entry.n;){
+     const size=Math.min(CHUNK,entry.n-offset);
+     const bytes=await take(size);
+     let saved=0;
+     while(saved<bytes.length){
+      const res=await handle.write(bytes,saved,bytes.length-saved,entry.o+offset+saved);
+      if(!res.bytesWritten)throw Error("Unable to persist restored file");
+      saved+=res.bytesWritten;
+     }
+     offset+=bytes.length;streamed+=bytes.length;
+    }
+    await handle.utimes(new Date(entry.m),new Date(entry.m)).catch(()=>{});
+   }finally{await handle.close();}
+  }
+  if(streamed!==idx.sourceBytes)throw Error("Restored pack payload did not match index");
+  restored+=idx.entries.length;
+  console.log("Restored "+(n+1)+"/"+packs.length+": "+idx.entries.length+" segments");
+ }
+ console.log("RESTORE COMPLETE: "+restored+" file segments from "+packs.length+" packs.");
+}
+async function main(){
+ const [action,target]=process.argv.slice(2);
+ if(!target||!["backup","restore"].includes(action))
+  throw Error("Usage: node TenCloud_BackupClient_v27.cjs backup|restore PATH");
+ await (action==="backup"?backup(target):restore(target));
+}
+if(require.main===module)main().catch(err=>{
+ console.error("TenCloud operation failed: "+err.message);process.exitCode=1;
+});
+module.exports={backup,restore,sendDirect,queryGoogle,stateFile,loadState,fingerprint,safeTarget,main};

package/lib/packformat.cjs

@@ -0,0 +1,134 @@
+"use strict";
+// TenCloud Pack V1: bounded-memory local plan/reader. No Worker ever sees file bytes.
+const fs=require("node:fs"),fsp=require("node:fs/promises"),path=require("node:path"),zlib=require("node:zlib");
+const MAX_PACK=64*1024*1024*1024;
+const MAX_SEGMENTS=10_000,MAX_MANIFEST=2*1024*1024;
+const MAX_DATA=MAX_PACK-MAX_MANIFEST-16;
+const HEADER_MAGIC="TENPACK1";
+async function* walk(root,rel=""){
+ if(!rel){
+  const st=await fsp.lstat(root);
+  if(st.isSymbolicLink())throw Error("Cannot upload symbolic-link source");
+  if(st.isFile()){
+   yield {name:path.basename(root),size:st.size,mtime:Math.floor(st.mtimeMs)};
+   return;
+  }
+  if(!st.isDirectory())throw Error("Source must be a regular file or directory");
+ }
+ const entries=await fsp.readdir(path.join(root,rel),{withFileTypes:true});
+ entries.sort((a,b)=>a.name.localeCompare(b.name));
+ for(const e of entries){
+  const name=path.join(rel,e.name);
+  if(e.isSymbolicLink())continue;
+  if(e.isDirectory())yield* walk(root,name);
+  else if(e.isFile()){
+   const st=await fsp.stat(path.join(root,name));
+   if(st.size>Number.MAX_SAFE_INTEGER)throw Error("Oversized input file: "+name);
+   const forward=name.split(path.sep).join("/");
+   if(Buffer.byteLength(forward,"utf8")>2048)throw Error("Path too long for backup pack");
+   yield {name:forward,size:st.size,mtime:Math.floor(st.mtimeMs)};
+  }
+ }
+}
+function serialize(entries,sourceBytes){
+ const manifest=Buffer.from(JSON.stringify({v:1,sourceBytes,entries}),"utf8");
+ const zip=zlib.gzipSync(manifest,{level:6});
+ if(zip.byteLength>MAX_MANIFEST)throw Error("Compressed index too large");
+ const header=Buffer.alloc(16);
+ header.write(HEADER_MAGIC,0,8,"ascii");
+ header.writeUInt32LE(zip.byteLength,8);
+ header.writeUInt32LE(entries.length,12);
+ return Buffer.concat([header,zip]);
+}
+async function* plans(root,{maxPackBytes=MAX_PACK,maxSegments=MAX_SEGMENTS}={}){
+ if(maxPackBytes>MAX_PACK||maxPackBytes<2*1024*1024||!Number.isSafeInteger(maxPackBytes))
+   throw Error("Pack size must be 2 MiB–64 GiB");
+ if(maxSegments>MAX_SEGMENTS||maxSegments<1)throw Error("Invalid pack entry bound");
+ const payloadMax=maxPackBytes-MAX_MANIFEST-16;
+ let entries=[],payload=0,packs=0;
+ function take(){
+  if(!entries.length)return null;
+  const header=serialize(entries,payload);
+  const plan={sequence:packs++,entries,header,payloadBytes:payload,
+   totalBytes:header.length+payload};
+  if(plan.totalBytes>maxPackBytes)throw Error("Planned pack unexpectedly exceeds configured size");
+  entries=[];payload=0;
+  return plan;
+ }
+ for await(const file of walk(root)){
+  let pos=0;
+  while(pos<file.size||file.size===0&&pos===0){
+   if(entries.length>=maxSegments||payload>=payloadMax){
+    const p=take();if(p)yield p;
+   }
+   const available=payloadMax-payload;
+   const n=file.size===0?0:Math.min(file.size-pos,available);
+   if(n<=0&&file.size>0){const p=take();if(p)yield p;continue;}
+   entries.push({p:file.name,o:pos,n,s:file.size,m:file.mtime,d:payload});
+   payload+=n;pos+=n;
+   if(file.size===0)break;
+   // Keep compressed header strictly bounded, not one D1 row per file.
+   if(entries.length%1000===0){
+     const zipped=serialize(entries,payload);
+     if(zipped.length>MAX_MANIFEST+16)throw Error("Index unexpectedly overflowed");
+   }
+  }
+ }
+ const last=take();if(last)yield last;
+}
+async function readSlice(root,plan,start,len){
+ if(!Number.isSafeInteger(start)||start<0||!Number.isSafeInteger(len)||len<0||start+len>plan.totalBytes)throw Error("Pack offset out of range");
+ const sourceRoot=(await fsp.lstat(root)).isFile()?path.dirname(root):root;
+ const output=Buffer.allocUnsafe(len);
+ let cursor=start,pos=0;
+ if(cursor<plan.header.byteLength){
+  const amount=Math.min(len,plan.header.length-cursor);
+  plan.header.copy(output,0,cursor,cursor+amount);
+  cursor+=amount;pos+=amount;
+ }
+ const payloadOffset=plan.header.length;
+ while(pos<len){
+  const relative=cursor-payloadOffset;
+  const entry=plan.entries.find(e=>e.n>0&&relative>=e.d&&relative<e.d+e.n);
+  if(!entry)throw Error("Gap in backup pack layout");
+  const inside=relative-entry.d,count=Math.min(len-pos,entry.n-inside);
+  const filePath=path.resolve(sourceRoot,...entry.p.split("/"));
+  if(!filePath.startsWith(path.resolve(sourceRoot)+path.sep))throw Error("Unexpected path escape");
+  const verified=await fsp.lstat(filePath);
+  if(!verified.isFile()||verified.isSymbolicLink()||verified.size!==entry.s||
+     Math.floor(verified.mtimeMs)!==entry.m)
+    throw Error("Backup source file changed after scanning: "+entry.p);
+  const fd=await fsp.open(filePath,"r");
+  try{
+   let n=0;while(n<count){
+    const r=await fd.read(output,pos+n,count-n,entry.o+inside+n);
+    if(r.bytesRead<=0)throw Error("File changed while uploading: "+entry.p);
+    n+=r.bytesRead;
+   }
+  }finally{await fd.close();}
+  cursor+=count;pos+=count;
+ }
+ return output;
+}
+function parseHeader(buf){
+ if(buf.length<16||buf.toString("ascii",0,8)!==HEADER_MAGIC)throw Error("Not a TenCloud Pack V1 file");
+ const zipLen=buf.readUInt32LE(8),files=buf.readUInt32LE(12);
+ if(zipLen<2||zipLen>MAX_MANIFEST||files<1||files>MAX_SEGMENTS)throw Error("Invalid pack header");
+ return {zipLen,files};
+}
+function parseManifest(header,zip){
+ const z=parseHeader(header);
+ if(zip.length!==z.zipLen)throw Error("Manifest truncated");
+ const decompressed=zlib.gunzipSync(zip,{maxOutputLength:12*1024*1024});
+ const json=JSON.parse(decompressed.toString("utf8"));
+ if(json.v!==1||!Array.isArray(json.entries)||json.entries.length!==z.files)throw Error("Invalid pack index");
+ let cursor=0;
+ for(const e of json.entries){
+  if(typeof e.p!=="string"||!Number.isSafeInteger(e.n)||!Number.isSafeInteger(e.s)||!Number.isSafeInteger(e.o)||!Number.isSafeInteger(e.d)||
+     e.n<0||e.o<0||e.d!==cursor||e.o+e.n>e.s)throw Error("Invalid pack range record");
+  cursor+=e.n;
+ }
+ if(cursor!==json.sourceBytes)throw Error("Pack payload/index lengths differ");
+ return json;
+}
+module.exports={walk,plans,readSlice,serialize,parseHeader,parseManifest,MAX_PACK,MAX_SEGMENTS,MAX_MANIFEST};

package/lib/sdk.cjs

@@ -0,0 +1,102 @@
+"use strict";
+/** TenCloud JavaScript SDK, Node 22+, uses the same resumable CLI engine. */
+const fs=require("node:fs/promises"),os=require("node:os"),path=require("node:path");
+const {spawn}=require("node:child_process");
+const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+class TenCloudClient{
+ constructor(options={}){
+  this.apiUrl=options.apiUrl||"https://api.cesiummc.space";
+  this.credentialsDirectory=options.credentialsDirectory||path.join(os.homedir(),".tencloud");
+  this.credentialsPath=path.join(this.credentialsDirectory,"credentials.json");
+ }
+ async _api(endpoint,options={}){
+  const response=await fetch(this.apiUrl+endpoint,{
+   method:options.method||"GET",headers:{accept:"application/json",...(options.body?{"content-type":"application/json"}:{}),...(options.token?{authorization:"Bearer "+options.token}:{})},
+   body:options.body?JSON.stringify(options.body):undefined,cache:"no-store",signal:options.signal||AbortSignal.timeout(40000)
+  });
+  const data=await response.json().catch(()=>({error:"Invalid JSON response"}));
+  return {response,data};
+ }
+ async getToken(){
+  if(process.env.TENCLOUD_API_KEY)return process.env.TENCLOUD_API_KEY;
+  try{
+   const saved=JSON.parse(await fs.readFile(this.credentialsPath,"utf8"));
+   return saved.api===this.apiUrl&&/^tc_live_[0-9a-f]{64}$/.test(saved.token||"")?saved.token:null;
+  }catch{return null;}
+ }
+ async _saveToken(token){
+  await fs.mkdir(this.credentialsDirectory,{recursive:true,mode:0o700});
+  const temp=this.credentialsPath+"."+process.pid+".tmp";
+  await fs.writeFile(temp,JSON.stringify({api:this.apiUrl,token},null,2),{mode:0o600,flag:"wx"});
+  await fs.rename(temp,this.credentialsPath);
+  if(process.platform!=="win32")await fs.chmod(this.credentialsPath,0o600);
+ }
+ async authenticate({onChallenge,signal}={}){
+  const start=await this._api("/v1/device/start",{method:"POST",body:{label:os.hostname().slice(0,40)||"TenCloud SDK"},signal});
+  if(!start.response.ok)throw Error("Device authorization failed: "+(start.data.error||start.response.status));
+  const challenge={
+   verificationUri:start.data.verification_uri,userCode:start.data.user_code,
+   expiresIn:start.data.expires_in
+  };
+  if(onChallenge)await onChallenge(challenge);
+  else console.log("Open "+challenge.verificationUri+" and enter "+challenge.userCode);
+  const expires=Date.now()+start.data.expires_in*1000;
+  const interval=Math.max(7000,start.data.interval*1000);
+  while(Date.now()<expires){
+   if(signal?.aborted)throw Error("Authorization cancelled");
+   await sleep(interval);
+   const {response,data}=await this._api("/v1/device/token",{method:"POST",body:{device_code:start.data.device_code},signal});
+   if(response.ok&&data.access_token){
+    const me=await this._api("/v1/me",{token:data.access_token,signal});
+    if(!me.response.ok)throw Error("Issued credential failed validation");
+    await this._saveToken(data.access_token);
+    return me.data;
+   }
+   if(["authorization_pending","slow_down"].includes(data.error))continue;
+   throw Error("Device authorization rejected: "+(data.error||response.status));
+  }
+  throw Error("Device authorization expired");
+ }
+ async account(){
+  const token=await this.getToken();
+  if(!token)throw Error("Not authenticated. Call authenticate()");
+  const {response,data}=await this._api("/v1/me",{token});
+  if(!response.ok)throw Error("Invalid or revoked TenCloud credential");
+  return data;
+ }
+ async _run(command,target,{onOutput,signal}={}){
+  if(!target)throw Error("Expected a local file or folder path");
+  if(!await this.getToken())throw Error("Not authenticated. Call authenticate()");
+  const argv=[path.join(__dirname,"..","bin","tencloud.cjs"),command,path.resolve(target)];
+  return new Promise((resolve,reject)=>{
+   const child=spawn(process.execPath,argv,{env:{...process.env,TENCLOUD_API_URL:this.apiUrl,TENCLOUD_CONFIG_DIR:this.credentialsDirectory},windowsHide:true,stdio:["ignore","pipe","pipe"]});
+   let output="",errors="",settled=false;
+   const report=(value,isError)=>{
+    if(isError)errors+=value;
+    else output+=value;
+    if(onOutput)onOutput(value,isError?"stderr":"stdout");
+   };
+   child.stdout.on("data",data=>report(data.toString("utf8"),false));
+   child.stderr.on("data",data=>report(data.toString("utf8"),true));
+   const abort=()=>child.kill();
+   if(signal){if(signal.aborted)abort();else signal.addEventListener("abort",abort,{once:true});}
+   child.on("error",error=>{if(!settled){settled=true;reject(error);}});
+   child.on("close",code=>{
+    if(signal)signal.removeEventListener("abort",abort);
+    if(settled)return;settled=true;
+    if(code===0)resolve({ok:true,output});
+    else reject(Error("TenCloud "+command+" failed: "+(errors||output||"process exited "+code).trim().slice(-1000)));
+   });
+  });
+ }
+ upload(localPath,options){return this._run("upload",localPath,options);}
+ uploadFile(localPath,options){return this.upload(localPath,options);}
+ uploadFolder(localPath,options){return this.upload(localPath,options);}
+ download(outputFolder,options){return this._run("download",outputFolder,options);}
+ async logout(){
+  await fs.rm(this.credentialsPath,{force:true});
+  return {localCredentialRemoved:true,serverCredentialStillValid:true};
+ }
+}
+const CesiumCloudClient=TenCloudClient;
+module.exports={CesiumCloudClient,TenCloudClient};

package/package.json

@@ -1,6 +1,28 @@
-{
-  "name": "cesiumcloud",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "cesiumcloud",
+  "version": "0.1.0",
+  "description": "CesiumCloud secure storage CLI and JavaScript SDK, compatible with existing TenCloud accounts.",
+  "license": "UNLICENSED",
+  "main": "lib/sdk.cjs",
+  "bin": {
+    "cesiumcloud": "bin/cesiumcloud.cjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "cesiumcloud",
+    "cloud",
+    "storage",
+    "backup"
+  ]
+}