@crewx/shared 0.0.6-rc.20 → 0.0.6-rc.22

package/crewx-api-credential.d.ts

@@ -0,0 +1,14 @@
+export type RuntimeCredentialPurpose = 'notify' | 'wi' | 'chromex-negotiate' | 'pairing';
+export interface ResolvedCredential {
+    token: string;
+    source: 'env' | 'file';
+}
+type CrewxCredentialErrorCode = 'MISSING' | 'BAD_MODE' | 'UNREADABLE';
+export declare class CrewxCredentialError extends Error {
+    readonly code: CrewxCredentialErrorCode;
+    readonly exitCode: number;
+    constructor(code: CrewxCredentialErrorCode, message: string);
+}
+export declare function resolveCrewxApiCredential(purpose: RuntimeCredentialPurpose, env?: NodeJS.ProcessEnv): ResolvedCredential;
+export declare function authorizationHeader(cred: ResolvedCredential): Record<'Authorization', string>;
+export {};

package/crewx-api-credential.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrewxCredentialError = void 0;
+exports.resolveCrewxApiCredential = resolveCrewxApiCredential;
+exports.authorizationHeader = authorizationHeader;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const sdk_1 = require("@crewx/sdk");
+const RUNTIME_CREDENTIAL_PURPOSES = new Set([
+    'notify',
+    'wi',
+    'chromex-negotiate',
+    'pairing',
+]);
+// These are sysexits-style values so shell callers can distinguish the local
+// credential failure before an HTTP request is attempted.
+const EXIT_CODES = {
+    MISSING: 78,
+    BAD_MODE: 77,
+    UNREADABLE: 74,
+};
+const HEX_64 = '[0-9a-f]{64}';
+class CrewxCredentialError extends Error {
+    code;
+    exitCode;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CrewxCredentialError';
+        this.code = code;
+        this.exitCode = EXIT_CODES[code];
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.CrewxCredentialError = CrewxCredentialError;
+function isErrnoCode(error, code) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === code;
+}
+function credentialPath(purpose) {
+    return path.join((0, sdk_1.getCrewxHome)(), 'auth', 'runtime', `${purpose}.token`);
+}
+function invalidPurpose(purpose) {
+    throw new TypeError(`Unsupported runtime credential purpose: ${String(purpose)}`);
+}
+function missingCredential(purpose, filePath) {
+    throw new CrewxCredentialError('MISSING', `Runtime credential '${purpose}' is missing at ${filePath}. `
+        + 'Run the CrewX server once to create it or set CREWX_API_TOKEN.');
+}
+function badMode(purpose, filePath) {
+    throw new CrewxCredentialError('BAD_MODE', `Runtime credential '${purpose}' at ${filePath} has insecure permissions; expected mode 0600.`);
+}
+function unreadableCredential(purpose, filePath) {
+    throw new CrewxCredentialError('UNREADABLE', `Runtime credential '${purpose}' at ${filePath} is unreadable or invalid. `
+        + 'Check the file contents and permissions.');
+}
+function readRuntimeCredential(purpose) {
+    const filePath = credentialPath(purpose);
+    let stats;
+    try {
+        // lstat prevents a symlink from bypassing the mode check on POSIX.
+        stats = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT'))
+            missingCredential(purpose, filePath);
+        unreadableCredential(purpose, filePath);
+    }
+    if (!stats.isFile())
+        unreadableCredential(purpose, filePath);
+    // Windows does not expose POSIX mode semantics; the server contract skips
+    // this check there as well.
+    if (process.platform !== 'win32' && (stats.mode & 0o777) !== 0o600) {
+        badMode(purpose, filePath);
+    }
+    let token;
+    try {
+        token = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT'))
+            missingCredential(purpose, filePath);
+        unreadableCredential(purpose, filePath);
+    }
+    const expected = new RegExp(`^crewxrt_${purpose}_${HEX_64}$`);
+    if (!expected.test(token))
+        unreadableCredential(purpose, filePath);
+    return token;
+}
+function resolveCrewxApiCredential(purpose, env = process.env) {
+    if (!RUNTIME_CREDENTIAL_PURPOSES.has(purpose))
+        invalidPurpose(purpose);
+    const envToken = env['CREWX_API_TOKEN'];
+    if (typeof envToken === 'string' && envToken.length > 0) {
+        return { token: envToken, source: 'env' };
+    }
+    return { token: readRuntimeCredential(purpose), source: 'file' };
+}
+function authorizationHeader(cred) {
+    return { Authorization: `Bearer ${cred.token}` };
+}

package/crewx-api-credential.ts

@@ -0,0 +1,131 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getCrewxHome } from '@crewx/sdk';
+
+export type RuntimeCredentialPurpose = 'notify' | 'wi' | 'chromex-negotiate' | 'pairing';
+
+export interface ResolvedCredential {
+  token: string;
+  source: 'env' | 'file';
+}
+
+type CrewxCredentialErrorCode = 'MISSING' | 'BAD_MODE' | 'UNREADABLE';
+
+const RUNTIME_CREDENTIAL_PURPOSES = new Set<RuntimeCredentialPurpose>([
+  'notify',
+  'wi',
+  'chromex-negotiate',
+  'pairing',
+]);
+
+// These are sysexits-style values so shell callers can distinguish the local
+// credential failure before an HTTP request is attempted.
+const EXIT_CODES: Record<CrewxCredentialErrorCode, number> = {
+  MISSING: 78,
+  BAD_MODE: 77,
+  UNREADABLE: 74,
+};
+
+const HEX_64 = '[0-9a-f]{64}';
+
+export class CrewxCredentialError extends Error {
+  readonly code: CrewxCredentialErrorCode;
+  readonly exitCode: number;
+
+  constructor(code: CrewxCredentialErrorCode, message: string) {
+    super(message);
+    this.name = 'CrewxCredentialError';
+    this.code = code;
+    this.exitCode = EXIT_CODES[code];
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function isErrnoCode(error: unknown, code: string): boolean {
+  return typeof error === 'object'
+    && error !== null
+    && 'code' in error
+    && (error as { code?: unknown }).code === code;
+}
+
+function credentialPath(purpose: RuntimeCredentialPurpose): string {
+  return path.join(getCrewxHome(), 'auth', 'runtime', `${purpose}.token`);
+}
+
+function invalidPurpose(purpose: RuntimeCredentialPurpose): never {
+  throw new TypeError(`Unsupported runtime credential purpose: ${String(purpose)}`);
+}
+
+function missingCredential(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'MISSING',
+    `Runtime credential '${purpose}' is missing at ${filePath}. `
+      + 'Run the CrewX server once to create it or set CREWX_API_TOKEN.',
+  );
+}
+
+function badMode(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'BAD_MODE',
+    `Runtime credential '${purpose}' at ${filePath} has insecure permissions; expected mode 0600.`,
+  );
+}
+
+function unreadableCredential(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'UNREADABLE',
+    `Runtime credential '${purpose}' at ${filePath} is unreadable or invalid. `
+      + 'Check the file contents and permissions.',
+  );
+}
+
+function readRuntimeCredential(purpose: RuntimeCredentialPurpose): string {
+  const filePath = credentialPath(purpose);
+  let stats: fs.Stats;
+
+  try {
+    // lstat prevents a symlink from bypassing the mode check on POSIX.
+    stats = fs.lstatSync(filePath);
+  } catch (error: unknown) {
+    if (isErrnoCode(error, 'ENOENT')) missingCredential(purpose, filePath);
+    unreadableCredential(purpose, filePath);
+  }
+
+  if (!stats!.isFile()) unreadableCredential(purpose, filePath);
+
+  // Windows does not expose POSIX mode semantics; the server contract skips
+  // this check there as well.
+  if (process.platform !== 'win32' && (stats!.mode & 0o777) !== 0o600) {
+    badMode(purpose, filePath);
+  }
+
+  let token: string;
+  try {
+    token = fs.readFileSync(filePath, 'utf8');
+  } catch (error: unknown) {
+    if (isErrnoCode(error, 'ENOENT')) missingCredential(purpose, filePath);
+    unreadableCredential(purpose, filePath);
+  }
+
+  const expected = new RegExp(`^crewxrt_${purpose}_${HEX_64}$`);
+  if (!expected.test(token!)) unreadableCredential(purpose, filePath);
+  return token!;
+}
+
+export function resolveCrewxApiCredential(
+  purpose: RuntimeCredentialPurpose,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedCredential {
+  if (!RUNTIME_CREDENTIAL_PURPOSES.has(purpose)) invalidPurpose(purpose);
+
+  const envToken = env['CREWX_API_TOKEN'];
+  if (typeof envToken === 'string' && envToken.length > 0) {
+    return { token: envToken, source: 'env' };
+  }
+
+  return { token: readRuntimeCredential(purpose), source: 'file' };
+}
+
+export function authorizationHeader(cred: ResolvedCredential): Record<'Authorization', string> {
+  return { Authorization: `Bearer ${cred.token}` };
+}

package/package.json

@@ -1,12 +1,41 @@
 {
   "name": "@crewx/shared",
-  "version": "0.0.6-rc.20",
+  "version": "0.0.6-rc.22",
   "main": "skill-tracer.js",
+  "exports": {
+    ".": {
+      "types": "./skill-tracer.d.ts",
+      "require": "./skill-tracer.js",
+      "default": "./skill-tracer.js"
+    },
+    "./skill-tracer": {
+      "types": "./skill-tracer.d.ts",
+      "require": "./skill-tracer.js",
+      "default": "./skill-tracer.js"
+    },
+    "./crewx-api-credential": {
+      "types": "./crewx-api-credential.d.ts",
+      "require": "./crewx-api-credential.js",
+      "default": "./crewx-api-credential.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "crewx-api-credential": [
+        "crewx-api-credential.d.ts"
+      ]
+    }
+  },
   "description": "Shared utilities for CrewX built-in packages",
   "dependencies": {
-    "@crewx/sdk": "0.8.9-rc.33"
+    "@crewx/sdk": "0.9.0-rc.107"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.json",
     "test": "echo no tests"
   }
 }

package/tests/crewx-api-credential.test.ts

@@ -0,0 +1,110 @@
+// @vitest-environment node
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  authorizationHeader,
+  CrewxCredentialError,
+  resolveCrewxApiCredential,
+} from '../crewx-api-credential';
+
+const VALID_HEX = 'a'.repeat(64);
+
+let tmpHome: string;
+const savedEnv = { ...process.env };
+
+function runtimePath(purpose: string): string {
+  return path.join(tmpHome, 'auth', 'runtime', `${purpose}.token`);
+}
+
+function writeCredential(purpose: string, mode = 0o600, token = `crewxrt_${purpose}_${VALID_HEX}`): void {
+  const file = runtimePath(purpose);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, token, { encoding: 'utf8', mode });
+  fs.chmodSync(file, mode);
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'crewx-runtime-credential-'));
+  process.env['CREWX_HOME'] = tmpHome;
+  delete process.env['CREWX_API_TOKEN'];
+});
+
+afterEach(() => {
+  process.env = { ...savedEnv };
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+describe('resolveCrewxApiCredential', () => {
+  it('resolves a purpose-scoped 0600 runtime credential and builds its Bearer header', () => {
+    writeCredential('notify');
+
+    const credential = resolveCrewxApiCredential('notify');
+
+    expect(credential).toEqual({ token: `crewxrt_notify_${VALID_HEX}`, source: 'file' });
+    expect(authorizationHeader(credential)).toEqual({
+      Authorization: `Bearer crewxrt_notify_${VALID_HEX}`,
+    });
+  });
+
+  it('resolves the pairing runtime credential', () => {
+    writeCredential('pairing');
+
+    expect(resolveCrewxApiCredential('pairing')).toEqual({
+      token: `crewxrt_pairing_${VALID_HEX}`,
+      source: 'file',
+    });
+  });
+
+  it('prefers CREWX_API_TOKEN without inspecting the runtime credential file', () => {
+    writeCredential('wi', 0o644);
+    process.env['CREWX_API_TOKEN'] = 'env-token';
+
+    expect(resolveCrewxApiCredential('wi')).toEqual({ token: 'env-token', source: 'env' });
+  });
+
+  it('fails with MISSING and a non-zero exit code when the runtime file is absent', () => {
+    expect(() => resolveCrewxApiCredential('notify')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('notify');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'MISSING', exitCode: expect.any(Number) });
+      expect((error as Error).message).toContain('notify.token');
+      expect((error as CrewxCredentialError).exitCode).toBe(78);
+    }
+  });
+
+  it('fails with a distinct BAD_MODE error when the runtime file is not 0600', () => {
+    writeCredential('notify', 0o644);
+
+    expect(() => resolveCrewxApiCredential('notify')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('notify');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'BAD_MODE', exitCode: expect.any(Number) });
+      expect((error as Error).message).toContain('0600');
+      expect((error as CrewxCredentialError).exitCode).toBe(77);
+    }
+  });
+
+  it('fails with UNREADABLE when the file content does not match the purpose contract', () => {
+    writeCredential('chromex-negotiate', 0o600, 'not-a-runtime-token');
+
+    expect(() => resolveCrewxApiCredential('chromex-negotiate')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('chromex-negotiate');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'UNREADABLE', exitCode: expect.any(Number) });
+      expect((error as CrewxCredentialError).exitCode).toBe(74);
+      expect((error as Error).message).not.toContain('not-a-runtime-token');
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "rootDir": ".",
+    "outDir": ".",
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["crewx-api-credential.ts"],
+  "exclude": ["node_modules", "tests"]
+}