@pulsarinteractive/geniustasker 0.1.0-beta.2 → 0.1.0-beta.4

package/src/store.mjs

@@ -11,56 +11,131 @@ import { fail } from './errors.mjs';
  * A hard crash deliberately leaves a lock/refresh marker rather than risking a
  * second use of a rotated refresh token. Doctor explains recovery. */
 export class CredentialStore {
-  constructor({ directory = join(homedir(), '.geniustasker'), context = 'default', lockTimeoutMs = 20000, maxBytes = 16384 } = {}) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/.test(context)) fail('invalid_arguments', 'Context names use 1–48 letters, numbers, underscores or hyphens.');
-    this.context = context; this.maxBytes = maxBytes;
-    this.directory = resolve(directory); this.path = join(this.directory, `${context}.json`); this.lockPath = `${this.path}.lock`; this.lockTimeoutMs = lockTimeoutMs;
+  constructor({
+    directory = join(homedir(), '.geniustasker'),
+    context = 'default',
+    lockTimeoutMs = 20000,
+    maxBytes = 16384,
+  } = {}) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/.test(context)) {
+      fail('invalid_arguments', 'Context names use 1–48 letters, numbers, underscores or hyphens.');
+    }
+    this.context = context;
+    this.maxBytes = maxBytes;
+    this.directory = resolve(directory);
+    this.path = join(this.directory, `${context}.json`);
+    this.lockPath = `${this.path}.lock`;
+    this.lockTimeoutMs = lockTimeoutMs;
   }
   async prepare() {
     await mkdir(this.directory, { recursive: true, mode: 0o700 });
     const stat = await lstat(this.directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || process.platform !== 'win32' && (stat.mode & 0o077))
-      fail('unsafe_credential_store', 'The credential directory must be private and owned by you.', { remediation: 'Use a dedicated directory with permissions 0700.' });
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      (process.getuid && stat.uid !== process.getuid()) ||
+      (process.platform !== 'win32' && stat.mode & 0o077)
+    ) {
+      fail(
+        'unsafe_credential_store',
+        'The credential directory must be private and owned by you.',
+        { remediation: 'Use a dedicated directory with permissions 0700.' },
+      );
+    }
   }
   async read() {
-    await this.prepare(); let handle;
-    try { handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW); }
-    catch (error) { if (error.code === 'ENOENT') return null; fail('unsafe_credential_store', 'The credential file could not be opened safely.'); }
+    await this.prepare();
+    let handle;
+    try {
+      handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+      fail('unsafe_credential_store', 'The credential file could not be opened safely.');
+    }
     try {
       const stat = await handle.stat();
-      if (!stat.isFile() || stat.nlink !== 1 || stat.size > this.maxBytes || process.platform !== 'win32' && (stat.mode & 0o077) || process.getuid && stat.uid !== process.getuid())
+      if (
+        !stat.isFile() ||
+        stat.nlink !== 1 ||
+        stat.size > this.maxBytes ||
+        (process.platform !== 'win32' && stat.mode & 0o077) ||
+        (process.getuid && stat.uid !== process.getuid())
+      ) {
         fail('unsafe_credential_store', 'The credential file must be private and owned by you.');
-      try { return JSON.parse(await handle.readFile('utf8')); }
-      catch { fail('invalid_credential_store', 'The credential file is damaged.', { remediation: 'Revoke the session in Account → Agents, then remove this context and log in again.' }); }
-    } finally { await handle.close(); }
+      }
+      try {
+        return JSON.parse(await handle.readFile('utf8'));
+      } catch {
+        fail('invalid_credential_store', 'The credential file is damaged.', {
+          remediation:
+            'Revoke the session in Account → Agents, then remove this context and log in again.',
+        });
+      }
+    } finally {
+      await handle.close();
+    }
   }
   async write(data) {
     const temporary = `${this.path}.${randomUUID()}.tmp`;
     const handle = await open(temporary, 'wx', 0o600);
-    try { await handle.writeFile(JSON.stringify(data)); await handle.sync(); }
-    finally { await handle.close(); }
+    try {
+      await handle.writeFile(JSON.stringify(data));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
     try {
       await rename(temporary, this.path);
       if (process.platform !== 'win32') {
         const directory = await open(this.directory, constants.O_RDONLY);
-        try { await directory.sync(); } finally { await directory.close(); }
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
       }
+    } finally {
+      await unlink(temporary).catch((error) => {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      });
     }
-    finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
   }
-  async remove() { await unlink(this.path).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+  async remove() {
+    await unlink(this.path).catch((error) => {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    });
+  }
   async locked(callback, signal) {
-    await this.prepare(); const deadline = Date.now() + this.lockTimeoutMs;
+    await this.prepare();
+    const deadline = Date.now() + this.lockTimeoutMs;
     while (true) {
-      try { await mkdir(this.lockPath, { mode: 0o700 }); break; }
-      catch (error) {
-        if (error.code !== 'EEXIST') throw error;
-        if (Date.now() >= deadline) fail('credential_store_busy', 'Another command owns this credential context.', { retryable: true,
-          remediation: 'Wait for that command. After a crash, stop all clients using this context, then remove its empty .lock directory.' });
+      try {
+        await mkdir(this.lockPath, { mode: 0o700 });
+        break;
+      } catch (error) {
+        if (error.code !== 'EEXIST') {
+          throw error;
+        }
+        if (Date.now() >= deadline) {
+          fail('credential_store_busy', 'Another command owns this credential context.', {
+            retryable: true,
+            remediation:
+              'Wait for that command. After a crash, stop all clients using this context, then remove its empty .lock directory.',
+          });
+        }
         await delay(50, undefined, { signal });
       }
     }
-    try { return await callback(); }
-    finally { await rmdir(this.lockPath); }
+    try {
+      return await callback();
+    } finally {
+      await rmdir(this.lockPath);
+    }
   }
 }

package/src/transport.mjs

@@ -1,68 +1,201 @@
 import { AgentError, fail } from './errors.mjs';
+import catalog from './command-catalog.mjs';
 
-export const ORIGINS = Object.freeze({ production: 'https://api-geniustasker.pulsarinteractive.cloud', development: 'https://dev-api-geniustasker.pulsarinteractive.cloud' });
+export const ORIGINS = Object.freeze({
+  production: 'https://api-geniustasker.pulsarinteractive.cloud',
+  development: 'https://dev-api-geniustasker.pulsarinteractive.cloud',
+});
 export const CLIENT_ID = 'geniustasker-cli';
+/** Resolve an approved API origin; loopback is available only by explicit opt-in. */
 export function originOf(value = ORIGINS.production, allowLocal = false) {
-  let url; try { url = new URL(value); } catch { fail('invalid_origin', 'An absolute API origin is required.'); }
-  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash ||
-      !(Object.values(ORIGINS).includes(url.origin) || allowLocal && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname)))
-    fail('invalid_origin', 'Use a GeniusTasker API origin or an explicit loopback origin with --allow-local.');
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail('invalid_origin', 'An absolute API origin is required.');
+  }
+  if (
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    !(
+      Object.values(ORIGINS).includes(url.origin) ||
+      (allowLocal && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))
+    )
+  ) {
+    fail(
+      'invalid_origin',
+      'Use a GeniusTasker API origin or an explicit loopback origin with --allow-local.',
+    );
+  }
   return url.origin;
 }
 
-const identifier = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,100}$/.test(value) ? value : undefined;
-const boundedText = value => typeof value === 'string' && value.length <= 500 && !/[\u0000-\u001f\u007f]/u.test(value) && !/gta1\.|wd[ar]_|sk-proj-/u.test(value) ? value : undefined;
+const identifier = (value) =>
+  typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,100}$/.test(value) ? value : undefined;
+const boundedText = (value) =>
+  typeof value === 'string' &&
+  value.length <= 500 &&
+  // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+  !/[\u0000-\u001f\u007f]/u.test(value) &&
+  !/gta1\.|wd[ar]_|sk-proj-/u.test(value)
+    ? value
+    : undefined;
+/**
+ * Bounded HTTP transport for delegated endpoints, with no implicit retries.
+ * Call originOf before construction; inject fetch/signal for controlled tests
+ * and operation-level cancellation. Error serialization excludes raw responses.
+ */
 export class Transport {
-  constructor(origin, { fetchImpl = fetch, timeoutMs = 15000, signal } = {}) { this.origin = origin; this.fetch = fetchImpl; this.timeoutMs = timeoutMs; this.signal = signal; }
-  async request(path, { method = 'GET', form, json, token, query } = {}) {
-    if (!(path.startsWith('/api/agents/') || path === '/.well-known/oauth-authorization-server') || path.startsWith('//'))
+  constructor(origin, { fetchImpl = fetch, timeoutMs = 15000, signal } = {}) {
+    this.origin = origin;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this.signal = signal;
+  }
+  async request(path, { method = 'GET', form, json, token, query, bytes, binary = false } = {}) {
+    if (
+      !(path.startsWith('/api/agents/') || path === '/.well-known/oauth-authorization-server') ||
+      path.startsWith('//')
+    ) {
       fail('invalid_arguments', 'Only delegated endpoints are available.');
+    }
     const url = new URL(path, this.origin);
-    if (url.origin !== this.origin || !(url.pathname.startsWith('/api/agents/') || url.pathname === '/.well-known/oauth-authorization-server'))
+    if (
+      url.origin !== this.origin ||
+      !(
+        url.pathname.startsWith('/api/agents/') ||
+        url.pathname === '/.well-known/oauth-authorization-server'
+      )
+    ) {
       fail('invalid_origin', 'Cross-origin or non-delegated requests are refused.');
-    if (query) for (const [key, value] of Object.entries(query)) if (value !== undefined) url.searchParams.set(key, String(value));
-    if (form && json !== undefined) fail('invalid_arguments', 'Choose one request body format.');
+    }
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    if (
+      (bytes !== undefined || binary) &&
+      (url.pathname !== '/api/agents/v1/media/content' ||
+        (bytes !== undefined && (!Buffer.isBuffer(bytes) || bytes.length > 15000000)) ||
+        (bytes !== undefined && (json !== undefined || form)))
+    ) {
+      fail('invalid_arguments', 'Binary transfer requires the bounded delegated media endpoint.');
+    }
+    if (form && json !== undefined) {
+      fail('invalid_arguments', 'Choose one request body format.');
+    }
     const jsonBody = json === undefined ? undefined : JSON.stringify(json);
-    if (jsonBody && Buffer.byteLength(jsonBody) > 32768) fail('invalid_arguments', 'Command exceeds the 32 KiB request limit.');
+    if (jsonBody && Buffer.byteLength(jsonBody) > catalog.maxCommandBytes) {
+      fail(
+        'invalid_arguments',
+        `Command exceeds the ${catalog.maxCommandBytes} byte request limit.`,
+      );
+    }
     let response;
     const timeout = AbortSignal.timeout(this.timeoutMs);
     const signal = this.signal ? AbortSignal.any([timeout, this.signal]) : timeout;
     try {
-      response = await this.fetch(url, { method, redirect: 'error', signal,
-        headers: { Accept: 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(form ? { 'Content-Type': 'application/x-www-form-urlencoded' } : jsonBody ? { 'Content-Type': 'application/json' } : {}) },
-        ...(form ? { body: new URLSearchParams(form) } : jsonBody ? { body: jsonBody } : {}) });
+      response = await this.fetch(url, {
+        method,
+        redirect: 'error',
+        signal,
+        headers: {
+          Accept: binary ? 'application/octet-stream' : 'application/json',
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+          ...(bytes !== undefined
+            ? { 'Content-Type': 'application/octet-stream', 'Content-Length': String(bytes.length) }
+            : form
+              ? { 'Content-Type': 'application/x-www-form-urlencoded' }
+              : jsonBody
+                ? { 'Content-Type': 'application/json' }
+                : {}),
+        },
+        ...(bytes !== undefined
+          ? { body: bytes }
+          : form
+            ? { body: new URLSearchParams(form) }
+            : jsonBody
+              ? { body: jsonBody }
+              : {}),
+      });
     } catch {
-      throw new AgentError('network_unavailable', 'The API did not return a usable response.', { retryable: true, remediation: 'Check connectivity. Authentication exchanges are never retried automatically.', execution: method === 'GET' ? 'not_applicable' : 'unknown' });
+      throw new AgentError('network_unavailable', 'The API did not return a usable response.', {
+        retryable: true,
+        remediation:
+          'Check connectivity. Authentication exchanges are never retried automatically.',
+        execution: method === 'GET' ? 'not_applicable' : 'unknown',
+      });
     }
-    const chunks = []; let size = 0;
+    const chunks = [];
+    let size = 0;
     try {
-      if (response.body) for await (const chunk of response.body) {
-        size += chunk.length;
-        if (size > 262144) fail('invalid_response', 'The API response exceeded the size limit.');
-        chunks.push(chunk);
+      if (response.body) {
+        for await (const chunk of response.body) {
+          size += chunk.length;
+          if (size > (binary && response.ok ? 15000000 : 262144)) {
+            fail('invalid_response', 'The API response exceeded the size limit.');
+          }
+          chunks.push(chunk);
+        }
       }
     } catch (error) {
-      if (error instanceof AgentError) throw error;
-      fail('network_unavailable', 'The API response was interrupted.', { retryable: true, execution: method === 'GET' ? 'not_applicable' : 'unknown' });
+      if (error instanceof AgentError) {
+        throw error;
+      }
+      fail('network_unavailable', 'The API response was interrupted.', {
+        retryable: true,
+        execution: method === 'GET' ? 'not_applicable' : 'unknown',
+      });
+    }
+    if (binary && response.ok) {
+      return Buffer.concat(chunks);
     }
     let data;
-    try { data = size ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : null; }
-    catch { fail('invalid_response', 'The API returned an unexpected format.', { status: response.status }); }
+    try {
+      data = size ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : null;
+    } catch {
+      fail('invalid_response', 'The API returned an unexpected format.', {
+        status: response.status,
+      });
+    }
     if (!response.ok) {
       const e = data?.error;
       const code = identifier(typeof e === 'string' ? e : e?.code) ?? 'api_error';
       const retry = Number(response.headers.get('Retry-After') ?? e?.retryAfterSeconds);
       throw new AgentError(code, boundedText(e?.message) ?? 'The API refused the request.', {
-        status: response.status, retryable: typeof e?.retryable === 'boolean' ? e.retryable : response.status === 429 || response.status === 503,
-        remediation: boundedText(e?.remediation) ?? (response.status === 401 ? 'Run auth login again; check the connection in Account → Agents.' : 'Check permissions, availability and command help.'),
+        status: response.status,
+        retryable:
+          typeof e?.retryable === 'boolean'
+            ? e.retryable
+            : response.status === 429 || response.status === 503,
+        remediation:
+          boundedText(e?.remediation) ??
+          (response.status === 401
+            ? 'Run auth login again; check the connection in Account → Agents.'
+            : 'Check permissions, availability and command help.'),
         ...(identifier(e?.requestId) ? { requestId: e.requestId } : {}),
-        ...(Number.isFinite(retry) && retry >= 0 && retry <= 86400 ? { retryAfterSeconds: retry } : {}),
-        ...(Number.isSafeInteger(data?.interval) && data.interval > 0 ? { interval: data.interval } : {}),
+        ...(Number.isFinite(retry) && retry >= 0 && retry <= 86400
+          ? { retryAfterSeconds: retry }
+          : {}),
+        ...(Number.isSafeInteger(data?.interval) && data.interval > 0
+          ? { interval: data.interval }
+          : {}),
         ...(identifier(e?.execution) ? { execution: e.execution } : {}),
         ...(Number.isSafeInteger(e?.resetAt) && e.resetAt > 0 ? { resetAt: e.resetAt } : {}),
       });
     }
     return data;
   }
-  oauth(endpoint, form) { return this.request(`/api/agents/oauth/${endpoint}`, { method: 'POST', form: { client_id: CLIENT_ID, ...form } }); }
+  oauth(endpoint, form) {
+    return this.request(`/api/agents/oauth/${endpoint}`, {
+      method: 'POST',
+      form: { client_id: CLIENT_ID, ...form },
+    });
+  }
 }