@heddleagent/execution-host-client 7.0.0 → 8.0.0

package/dist/node/local-credential-bundle.js

@@ -0,0 +1,196 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, mkdtemp, rename, rm, } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { generateExecutionAuthorityKeyFile, loadExecutionAuthorityKeyPairFromFile, } from './authority-key.js';
+import { createOwnerOnlyFile, OwnerOnlyFileError, readOwnerOnlyFile, removeOneTrailingLineEnding, } from './owner-only-file.js';
+const BUNDLE_KIND = 'heddle-execution-host-local-credentials';
+const BUNDLE_SCHEMA_VERSION = 2;
+const MAX_BUNDLE_FILE_BYTES = 16 * 1_024;
+const OWNER_DIRECTORY_MODE = 0o700;
+const TokenSchema = z.string().regex(/^[a-f0-9]{64}$/);
+export const LOCAL_CREDENTIAL_BUNDLE_FILES = Object.freeze({
+    executionHostLocalToken: 'execution-host-local-token',
+    executionHostLocalTokenSha256: 'execution-host-local-token.sha256',
+    coordinatorApiToken: 'coordinator-api-token',
+    coordinatorProductExecutionToken: 'coordinator-product-execution-token',
+    executionAuthorityPrivateJwk: 'execution-authority-private.jwk',
+    manifest: 'manifest.json',
+});
+const SecretBundleFilesSchema = z.object({
+    executionHostLocalToken: z.literal(LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken),
+    executionHostLocalTokenSha256: z.literal(LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256),
+    coordinatorApiToken: z.literal(LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken),
+    coordinatorProductExecutionToken: z.literal(LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken),
+    executionAuthorityPrivateJwk: z.literal(LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk),
+}).strict();
+const LocalCredentialBundleManifestSchema = z.object({
+    kind: z.literal(BUNDLE_KIND),
+    schemaVersion: z.literal(BUNDLE_SCHEMA_VERSION),
+    files: SecretBundleFilesSchema,
+}).strict();
+/**
+ * Creates one versioned, owner-only credential bundle for local hosted-service
+ * composition. A valid existing bundle is returned unchanged; partial or
+ * unmanaged directories fail closed.
+ */
+export async function initializeLocalCredentialBundle(rawOutputDirectory) {
+    const outputDirectory = resolveOutputDirectory(rawOutputDirectory);
+    const existing = await pathExists(outputDirectory);
+    if (existing) {
+        return {
+            created: false,
+            paths: await validateLocalCredentialBundle(outputDirectory),
+        };
+    }
+    const parentDirectory = dirname(outputDirectory);
+    await mkdir(parentDirectory, { recursive: true, mode: OWNER_DIRECTORY_MODE });
+    const temporaryDirectory = await mkdtemp(join(parentDirectory, `.${basename(outputDirectory)}.tmp-`));
+    await chmod(temporaryDirectory, OWNER_DIRECTORY_MODE);
+    try {
+        await populateCredentialBundle(temporaryDirectory);
+        let created = true;
+        try {
+            await rename(temporaryDirectory, outputDirectory);
+        }
+        catch (error) {
+            if (!(await pathExists(outputDirectory))) {
+                throw error;
+            }
+            await rm(temporaryDirectory, { recursive: true, force: true });
+            created = false;
+        }
+        return {
+            created,
+            paths: await validateLocalCredentialBundle(outputDirectory),
+        };
+    }
+    catch (error) {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+        if (error instanceof LocalCredentialBundleError) {
+            throw error;
+        }
+        throw new LocalCredentialBundleError('Local Execution Host credentials could not be initialized.');
+    }
+}
+/** Validates one generated bundle without returning any credential value. */
+export async function validateLocalCredentialBundle(rawDirectory) {
+    const directory = resolveOutputDirectory(rawDirectory);
+    try {
+        await assertOwnerOnlyDirectory(directory);
+        const paths = resolveBundlePaths(directory);
+        LocalCredentialBundleManifestSchema.parse(JSON.parse(await readBundleEntry(paths.manifest)));
+        const [localToken, localTokenDigest, coordinatorToken, productExecutionToken,] = await Promise.all([
+            readBundleEntry(paths.executionHostLocalToken),
+            readBundleEntry(paths.executionHostLocalTokenSha256),
+            readBundleEntry(paths.coordinatorApiToken),
+            readBundleEntry(paths.coordinatorProductExecutionToken),
+        ]);
+        TokenSchema.parse(localToken);
+        TokenSchema.parse(localTokenDigest);
+        TokenSchema.parse(coordinatorToken);
+        TokenSchema.parse(productExecutionToken);
+        if (sha256(localToken) !== localTokenDigest) {
+            throw new LocalCredentialBundleError('Local credential bundle token verifier does not match its token.');
+        }
+        await loadExecutionAuthorityKeyPairFromFile(paths.executionAuthorityPrivateJwk);
+        return Object.freeze(paths);
+    }
+    catch (error) {
+        if (error instanceof LocalCredentialBundleError) {
+            throw error;
+        }
+        if (error instanceof OwnerOnlyFileError) {
+            throw new LocalCredentialBundleError(error.message);
+        }
+        throw new LocalCredentialBundleError('Existing local credential directory is incomplete, invalid, or unmanaged.');
+    }
+}
+async function populateCredentialBundle(directory) {
+    const paths = resolveBundlePaths(directory);
+    const localToken = generateToken();
+    await Promise.all([
+        writeBundleEntry(paths.executionHostLocalToken, localToken),
+        writeBundleEntry(paths.executionHostLocalTokenSha256, sha256(localToken)),
+        writeBundleEntry(paths.coordinatorApiToken, generateToken()),
+        writeBundleEntry(paths.coordinatorProductExecutionToken, generateToken()),
+        generateExecutionAuthorityKeyFile(paths.executionAuthorityPrivateJwk),
+    ]);
+    await writeBundleEntry(paths.manifest, JSON.stringify({
+        kind: BUNDLE_KIND,
+        schemaVersion: BUNDLE_SCHEMA_VERSION,
+        files: secretFileManifest(),
+    }, null, 2));
+}
+function secretFileManifest() {
+    return {
+        executionHostLocalToken: LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken,
+        executionHostLocalTokenSha256: LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256,
+        coordinatorApiToken: LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken,
+        coordinatorProductExecutionToken: LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken,
+        executionAuthorityPrivateJwk: LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk,
+    };
+}
+function resolveBundlePaths(directory) {
+    return {
+        directory,
+        manifest: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.manifest),
+        executionHostLocalToken: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken),
+        executionHostLocalTokenSha256: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256),
+        coordinatorApiToken: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken),
+        coordinatorProductExecutionToken: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken),
+        executionAuthorityPrivateJwk: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk),
+    };
+}
+function resolveOutputDirectory(rawDirectory) {
+    const directory = rawDirectory.trim();
+    if (!directory) {
+        throw new LocalCredentialBundleError('A local credential output directory is required.');
+    }
+    return resolve(directory);
+}
+async function assertOwnerOnlyDirectory(directory) {
+    const metadata = await lstat(directory);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new LocalCredentialBundleError('Local credential bundle path must be a real directory.');
+    }
+    if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+        throw new LocalCredentialBundleError('Local credential bundle directory must not be group- or world-accessible.');
+    }
+}
+async function readBundleEntry(filePath) {
+    return removeOneTrailingLineEnding(await readOwnerOnlyFile(filePath, {
+        description: 'Local credential bundle entry',
+        maxBytes: MAX_BUNDLE_FILE_BYTES,
+    }));
+}
+function writeBundleEntry(filePath, value) {
+    return createOwnerOnlyFile(filePath, `${value}\n`);
+}
+function generateToken() {
+    return randomBytes(32).toString('hex');
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT')) {
+            return false;
+        }
+        throw new LocalCredentialBundleError('Local credential bundle path could not be inspected.');
+    }
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error
+        && 'code' in error
+        && error.code === code;
+}
+export class LocalCredentialBundleError extends Error {
+    name = 'LocalCredentialBundleError';
+}
+//# sourceMappingURL=local-credential-bundle.js.map

package/dist/node/local-credential-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-credential-bundle.js","sourceRoot":"","sources":["../../src/node/local-credential-bundle.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomBytes } from 'node:crypto';\nimport {\n  chmod,\n  lstat,\n  mkdir,\n  mkdtemp,\n  rename,\n  rm,\n} from 'node:fs/promises';\nimport { basename, dirname, join, resolve } from 'node:path';\nimport { z } from 'zod';\nimport {\n  generateExecutionAuthorityKeyFile,\n  loadExecutionAuthorityKeyPairFromFile,\n} from './authority-key.js';\nimport {\n  createOwnerOnlyFile,\n  OwnerOnlyFileError,\n  readOwnerOnlyFile,\n  removeOneTrailingLineEnding,\n} from './owner-only-file.js';\n\nconst BUNDLE_KIND = 'heddle-execution-host-local-credentials';\nconst BUNDLE_SCHEMA_VERSION = 2;\nconst MAX_BUNDLE_FILE_BYTES = 16 * 1_024;\nconst OWNER_DIRECTORY_MODE = 0o700;\nconst TokenSchema = z.string().regex(/^[a-f0-9]{64}$/);\n\nexport const LOCAL_CREDENTIAL_BUNDLE_FILES = Object.freeze({\n  executionHostLocalToken: 'execution-host-local-token',\n  executionHostLocalTokenSha256: 'execution-host-local-token.sha256',\n  coordinatorApiToken: 'coordinator-api-token',\n  coordinatorProductExecutionToken: 'coordinator-product-execution-token',\n  executionAuthorityPrivateJwk: 'execution-authority-private.jwk',\n  manifest: 'manifest.json',\n} as const);\n\nconst SecretBundleFilesSchema = z.object({\n  executionHostLocalToken: z.literal(\n    LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken,\n  ),\n  executionHostLocalTokenSha256: z.literal(\n    LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256,\n  ),\n  coordinatorApiToken: z.literal(\n    LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken,\n  ),\n  coordinatorProductExecutionToken: z.literal(\n    LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken,\n  ),\n  executionAuthorityPrivateJwk: z.literal(\n    LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk,\n  ),\n}).strict();\n\nconst LocalCredentialBundleManifestSchema = z.object({\n  kind: z.literal(BUNDLE_KIND),\n  schemaVersion: z.literal(BUNDLE_SCHEMA_VERSION),\n  files: SecretBundleFilesSchema,\n}).strict();\n\nexport type LocalCredentialBundlePaths = {\n  directory: string;\n  manifest: string;\n  executionHostLocalToken: string;\n  executionHostLocalTokenSha256: string;\n  coordinatorApiToken: string;\n  coordinatorProductExecutionToken: string;\n  executionAuthorityPrivateJwk: string;\n};\n\nexport type LocalCredentialBundleInitialization = {\n  created: boolean;\n  paths: LocalCredentialBundlePaths;\n};\n\n/**\n * Creates one versioned, owner-only credential bundle for local hosted-service\n * composition. A valid existing bundle is returned unchanged; partial or\n * unmanaged directories fail closed.\n */\nexport async function initializeLocalCredentialBundle(\n  rawOutputDirectory: string,\n): Promise<LocalCredentialBundleInitialization> {\n  const outputDirectory = resolveOutputDirectory(rawOutputDirectory);\n  const existing = await pathExists(outputDirectory);\n  if (existing) {\n    return {\n      created: false,\n      paths: await validateLocalCredentialBundle(outputDirectory),\n    };\n  }\n\n  const parentDirectory = dirname(outputDirectory);\n  await mkdir(parentDirectory, { recursive: true, mode: OWNER_DIRECTORY_MODE });\n  const temporaryDirectory = await mkdtemp(join(\n    parentDirectory,\n    `.${basename(outputDirectory)}.tmp-`,\n  ));\n  await chmod(temporaryDirectory, OWNER_DIRECTORY_MODE);\n\n  try {\n    await populateCredentialBundle(temporaryDirectory);\n    let created = true;\n    try {\n      await rename(temporaryDirectory, outputDirectory);\n    } catch (error) {\n      if (!(await pathExists(outputDirectory))) {\n        throw error;\n      }\n      await rm(temporaryDirectory, { recursive: true, force: true });\n      created = false;\n    }\n    return {\n      created,\n      paths: await validateLocalCredentialBundle(outputDirectory),\n    };\n  } catch (error) {\n    await rm(temporaryDirectory, { recursive: true, force: true });\n    if (error instanceof LocalCredentialBundleError) {\n      throw error;\n    }\n    throw new LocalCredentialBundleError(\n      'Local Execution Host credentials could not be initialized.',\n    );\n  }\n}\n\n/** Validates one generated bundle without returning any credential value. */\nexport async function validateLocalCredentialBundle(\n  rawDirectory: string,\n): Promise<LocalCredentialBundlePaths> {\n  const directory = resolveOutputDirectory(rawDirectory);\n  try {\n    await assertOwnerOnlyDirectory(directory);\n    const paths = resolveBundlePaths(directory);\n    LocalCredentialBundleManifestSchema.parse(\n      JSON.parse(await readBundleEntry(paths.manifest)) as unknown,\n    );\n\n    const [\n      localToken,\n      localTokenDigest,\n      coordinatorToken,\n      productExecutionToken,\n    ] = await Promise.all([\n      readBundleEntry(paths.executionHostLocalToken),\n      readBundleEntry(paths.executionHostLocalTokenSha256),\n      readBundleEntry(paths.coordinatorApiToken),\n      readBundleEntry(paths.coordinatorProductExecutionToken),\n    ]);\n    TokenSchema.parse(localToken);\n    TokenSchema.parse(localTokenDigest);\n    TokenSchema.parse(coordinatorToken);\n    TokenSchema.parse(productExecutionToken);\n    if (sha256(localToken) !== localTokenDigest) {\n      throw new LocalCredentialBundleError(\n        'Local credential bundle token verifier does not match its token.',\n      );\n    }\n    await loadExecutionAuthorityKeyPairFromFile(\n      paths.executionAuthorityPrivateJwk,\n    );\n    return Object.freeze(paths);\n  } catch (error) {\n    if (error instanceof LocalCredentialBundleError) {\n      throw error;\n    }\n    if (error instanceof OwnerOnlyFileError) {\n      throw new LocalCredentialBundleError(error.message);\n    }\n    throw new LocalCredentialBundleError(\n      'Existing local credential directory is incomplete, invalid, or unmanaged.',\n    );\n  }\n}\n\nasync function populateCredentialBundle(directory: string): Promise<void> {\n  const paths = resolveBundlePaths(directory);\n  const localToken = generateToken();\n  await Promise.all([\n    writeBundleEntry(paths.executionHostLocalToken, localToken),\n    writeBundleEntry(\n      paths.executionHostLocalTokenSha256,\n      sha256(localToken),\n    ),\n    writeBundleEntry(paths.coordinatorApiToken, generateToken()),\n    writeBundleEntry(\n      paths.coordinatorProductExecutionToken,\n      generateToken(),\n    ),\n    generateExecutionAuthorityKeyFile(paths.executionAuthorityPrivateJwk),\n  ]);\n  await writeBundleEntry(paths.manifest, JSON.stringify({\n    kind: BUNDLE_KIND,\n    schemaVersion: BUNDLE_SCHEMA_VERSION,\n    files: secretFileManifest(),\n  }, null, 2));\n}\n\nfunction secretFileManifest() {\n  return {\n    executionHostLocalToken:\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken,\n    executionHostLocalTokenSha256:\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256,\n    coordinatorApiToken: LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken,\n    coordinatorProductExecutionToken:\n      LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken,\n    executionAuthorityPrivateJwk:\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk,\n  } as const;\n}\n\nfunction resolveBundlePaths(directory: string): LocalCredentialBundlePaths {\n  return {\n    directory,\n    manifest: join(directory, LOCAL_CREDENTIAL_BUNDLE_FILES.manifest),\n    executionHostLocalToken: join(\n      directory,\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalToken,\n    ),\n    executionHostLocalTokenSha256: join(\n      directory,\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionHostLocalTokenSha256,\n    ),\n    coordinatorApiToken: join(\n      directory,\n      LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorApiToken,\n    ),\n    coordinatorProductExecutionToken: join(\n      directory,\n      LOCAL_CREDENTIAL_BUNDLE_FILES.coordinatorProductExecutionToken,\n    ),\n    executionAuthorityPrivateJwk: join(\n      directory,\n      LOCAL_CREDENTIAL_BUNDLE_FILES.executionAuthorityPrivateJwk,\n    ),\n  };\n}\n\nfunction resolveOutputDirectory(rawDirectory: string): string {\n  const directory = rawDirectory.trim();\n  if (!directory) {\n    throw new LocalCredentialBundleError(\n      'A local credential output directory is required.',\n    );\n  }\n  return resolve(directory);\n}\n\nasync function assertOwnerOnlyDirectory(directory: string): Promise<void> {\n  const metadata = await lstat(directory);\n  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {\n    throw new LocalCredentialBundleError(\n      'Local credential bundle path must be a real directory.',\n    );\n  }\n  if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {\n    throw new LocalCredentialBundleError(\n      'Local credential bundle directory must not be group- or world-accessible.',\n    );\n  }\n}\n\nasync function readBundleEntry(filePath: string): Promise<string> {\n  return removeOneTrailingLineEnding(await readOwnerOnlyFile(filePath, {\n    description: 'Local credential bundle entry',\n    maxBytes: MAX_BUNDLE_FILE_BYTES,\n  }));\n}\n\nfunction writeBundleEntry(filePath: string, value: string): Promise<void> {\n  return createOwnerOnlyFile(filePath, `${value}\\n`);\n}\n\nfunction generateToken(): string {\n  return randomBytes(32).toString('hex');\n}\n\nfunction sha256(value: string): string {\n  return createHash('sha256').update(value, 'utf8').digest('hex');\n}\n\nasync function pathExists(path: string): Promise<boolean> {\n  try {\n    await lstat(path);\n    return true;\n  } catch (error) {\n    if (isErrnoCode(error, 'ENOENT')) {\n      return false;\n    }\n    throw new LocalCredentialBundleError(\n      'Local credential bundle path could not be inspected.',\n    );\n  }\n}\n\nfunction isErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error\n    && 'code' in error\n    && error.code === code;\n}\n\nexport class LocalCredentialBundleError extends Error {\n  readonly name = 'LocalCredentialBundleError';\n}\n"]}

package/dist/node/owner-only-file.d.ts

@@ -0,0 +1,17 @@
+type OwnerOnlyFileReadOptions = {
+    description: string;
+    maxBytes: number;
+};
+/**
+ * Reads a bounded regular file without following its final symlink and rejects
+ * group- or world-accessible POSIX files.
+ */
+export declare function readOwnerOnlyFile(filePath: string, options: OwnerOnlyFileReadOptions): Promise<string>;
+/** Creates, flushes, and never overwrites one owner-only file. */
+export declare function createOwnerOnlyFile(filePath: string, value: string): Promise<void>;
+export declare function removeOneTrailingLineEnding(value: string): string;
+export declare class OwnerOnlyFileError extends Error {
+    readonly name = "OwnerOnlyFileError";
+}
+export {};
+//# sourceMappingURL=owner-only-file.d.ts.map

package/dist/node/owner-only-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-only-file.d.ts","sourceRoot":"","sources":["../../src/node/owner-only-file.ts"],"names":[],"mappings":"AASA,KAAK,wBAAwB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED,kEAAkE;AAClE,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjE;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,wBAAwB;CACtC"}

package/dist/node/owner-only-file.js

@@ -0,0 +1,59 @@
+import { constants } from 'node:fs';
+import { open, unlink, } from 'node:fs/promises';
+const OWNER_FILE_MODE = 0o600;
+/**
+ * Reads a bounded regular file without following its final symlink and rejects
+ * group- or world-accessible POSIX files.
+ */
+export async function readOwnerOnlyFile(filePath, options) {
+    let file;
+    try {
+        file = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const metadata = await file.stat();
+        if (!metadata.isFile()
+            || metadata.size <= 0
+            || metadata.size > options.maxBytes) {
+            throw new OwnerOnlyFileError(`${options.description} must be a non-empty regular file no larger than ${options.maxBytes} bytes.`);
+        }
+        if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+            throw new OwnerOnlyFileError(`${options.description} must not be group- or world-accessible.`);
+        }
+        return await file.readFile('utf8');
+    }
+    finally {
+        await file?.close().catch(() => undefined);
+    }
+}
+/** Creates, flushes, and never overwrites one owner-only file. */
+export async function createOwnerOnlyFile(filePath, value) {
+    let file;
+    let created = false;
+    try {
+        file = await open(filePath, 'wx', OWNER_FILE_MODE);
+        created = true;
+        await file.writeFile(value, 'utf8');
+        await file.sync();
+    }
+    catch (error) {
+        await file?.close().catch(() => undefined);
+        file = undefined;
+        if (created) {
+            await unlink(filePath).catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        await file?.close().catch(() => undefined);
+    }
+}
+export function removeOneTrailingLineEnding(value) {
+    return value.endsWith('\r\n')
+        ? value.slice(0, -2)
+        : value.endsWith('\n')
+            ? value.slice(0, -1)
+            : value;
+}
+export class OwnerOnlyFileError extends Error {
+    name = 'OwnerOnlyFileError';
+}
+//# sourceMappingURL=owner-only-file.js.map

package/dist/node/owner-only-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-only-file.js","sourceRoot":"","sources":["../../src/node/owner-only-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EACL,IAAI,EACJ,MAAM,GAEP,MAAM,kBAAkB,CAAC;AAE1B,MAAM,eAAe,GAAG,KAAK,CAAC;AAO9B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,OAAiC;IAEjC,IAAI,IAA4B,CAAC;IACjC,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACnC,IACE,CAAC,QAAQ,CAAC,MAAM,EAAE;eACf,QAAQ,CAAC,IAAI,IAAI,CAAC;eAClB,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,QAAQ,EACnC,CAAC;YACD,MAAM,IAAI,kBAAkB,CAC1B,GAAG,OAAO,CAAC,WAAW,oDAAoD,OAAO,CAAC,QAAQ,SAAS,CACpG,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,kBAAkB,CAC1B,GAAG,OAAO,CAAC,WAAW,0CAA0C,CACjE,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAChB,KAAa;IAEb,IAAI,IAA4B,CAAC;IACjC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;QACnD,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,GAAG,SAAS,CAAC;QACjB,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC3B,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YACpB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,KAAK,CAAC;AACd,CAAC;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,oBAAoB,CAAC;CACtC","sourcesContent":["import { constants } from 'node:fs';\nimport {\n  open,\n  unlink,\n  type FileHandle,\n} from 'node:fs/promises';\n\nconst OWNER_FILE_MODE = 0o600;\n\ntype OwnerOnlyFileReadOptions = {\n  description: string;\n  maxBytes: number;\n};\n\n/**\n * Reads a bounded regular file without following its final symlink and rejects\n * group- or world-accessible POSIX files.\n */\nexport async function readOwnerOnlyFile(\n  filePath: string,\n  options: OwnerOnlyFileReadOptions,\n): Promise<string> {\n  let file: FileHandle | undefined;\n  try {\n    file = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);\n    const metadata = await file.stat();\n    if (\n      !metadata.isFile()\n      || metadata.size <= 0\n      || metadata.size > options.maxBytes\n    ) {\n      throw new OwnerOnlyFileError(\n        `${options.description} must be a non-empty regular file no larger than ${options.maxBytes} bytes.`,\n      );\n    }\n    if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {\n      throw new OwnerOnlyFileError(\n        `${options.description} must not be group- or world-accessible.`,\n      );\n    }\n    return await file.readFile('utf8');\n  } finally {\n    await file?.close().catch(() => undefined);\n  }\n}\n\n/** Creates, flushes, and never overwrites one owner-only file. */\nexport async function createOwnerOnlyFile(\n  filePath: string,\n  value: string,\n): Promise<void> {\n  let file: FileHandle | undefined;\n  let created = false;\n  try {\n    file = await open(filePath, 'wx', OWNER_FILE_MODE);\n    created = true;\n    await file.writeFile(value, 'utf8');\n    await file.sync();\n  } catch (error) {\n    await file?.close().catch(() => undefined);\n    file = undefined;\n    if (created) {\n      await unlink(filePath).catch(() => undefined);\n    }\n    throw error;\n  } finally {\n    await file?.close().catch(() => undefined);\n  }\n}\n\nexport function removeOneTrailingLineEnding(value: string): string {\n  return value.endsWith('\\r\\n')\n    ? value.slice(0, -2)\n    : value.endsWith('\\n')\n      ? value.slice(0, -1)\n      : value;\n}\n\nexport class OwnerOnlyFileError extends Error {\n  readonly name = 'OwnerOnlyFileError';\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heddleagent/execution-host-client",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Contracts, execution authority, lifecycle services, and adopter clients for compatible Heddle Execution Hosts",
   "author": "Jay / Fienna Liang <roackb2@gmail.com>",
   "license": "MIT",
@@ -20,6 +20,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "heddle-hostctl": "./dist/cli/hostctl.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -115,6 +118,7 @@
     "@aws-sdk/client-bedrock-agentcore": "^3.1107.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@smithy/protocol-http": "^5.5.16",
+    "commander": "^14.0.3",
     "dayjs": "^1.11.20",
     "eventsource-parser": "^3.1.0",
     "jose": "^6.2.8",

package/dist/coordinator/hosted-heartbeat-delegation-client.d.ts

@@ -1,21 +0,0 @@
-import { type HostedHeartbeatAgentExecutionTransportInput } from '../heartbeat/index.js';
-import { type HostedHeartbeatDelegation, type HostedHeartbeatDelegationRequest } from './contracts.js';
-import type { HostedHeartbeatDelegatedExecutionTransportConfig, HostedHeartbeatDelegatedExecutionTransportPort, HostedHeartbeatDelegationClientConfig, HostedHeartbeatDelegationIssuer } from './types.js';
-export declare class HostedHeartbeatDelegationRequestError extends Error {
-    readonly status: number;
-    readonly name = "HostedHeartbeatDelegationRequestError";
-    constructor(status: number);
-}
-/** Authenticated coordinator client for one product-issued authority bundle. */
-export declare class HostedHeartbeatDelegationClient implements HostedHeartbeatDelegationIssuer {
-    #private;
-    constructor(config: HostedHeartbeatDelegationClientConfig);
-    issue(rawInput: HostedHeartbeatDelegationRequest, signal?: AbortSignal): Promise<HostedHeartbeatDelegation>;
-}
-/** Executes a claimed task with the exact product-issued authority bundle. */
-export declare class HostedHeartbeatDelegatedExecutionTransport implements HostedHeartbeatDelegatedExecutionTransportPort {
-    #private;
-    constructor(config: HostedHeartbeatDelegatedExecutionTransportConfig);
-    execute(input: HostedHeartbeatAgentExecutionTransportInput): Promise<unknown>;
-}
-//# sourceMappingURL=hosted-heartbeat-delegation-client.d.ts.map

package/dist/coordinator/hosted-heartbeat-delegation-client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hosted-heartbeat-delegation-client.d.ts","sourceRoot":"","sources":["../../src/coordinator/hosted-heartbeat-delegation-client.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,2CAA2C,EACjD,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIL,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACtC,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EACV,gDAAgD,EAChD,8CAA8C,EAC9C,qCAAqC,EACrC,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAWpB,qBAAa,qCAAsC,SAAQ,KAAK;IAGlD,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFnC,QAAQ,CAAC,IAAI,2CAA2C;gBAEnC,MAAM,EAAE,MAAM;CAGpC;AAED,gFAAgF;AAChF,qBAAa,+BACb,YAAW,+BAA+B;;gBAK5B,MAAM,EAAE,qCAAqC;IAcnD,KAAK,CACT,QAAQ,EAAE,gCAAgC,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,yBAAyB,CAAC;CA4BtC;AAED,8EAA8E;AAC9E,qBAAa,0CACb,YAAW,8CAA8C;;gBAG3C,MAAM,EAAE,gDAAgD;IAI9D,OAAO,CACX,KAAK,EAAE,2CAA2C,GACjD,OAAO,CAAC,OAAO,CAAC;CAwBpB"}

package/dist/coordinator/hosted-heartbeat-delegation-client.js

@@ -1,117 +0,0 @@
-import { z } from 'zod';
-import { HEARTBEAT_TASK_WORKFLOW, isSafeWebUrl, } from '../contracts/index.js';
-import { HostedHeartbeatAgentExecutionTransport, HostedHeartbeatTaskService, } from '../heartbeat/index.js';
-import { HOSTED_HEARTBEAT_DELEGATIONS_PATH, HostedHeartbeatDelegationRequestSchema, HostedHeartbeatDelegationSchema, } from './contracts.js';
-import { HostedHeartbeatServiceTokenSchema } from './service-token.js';
-const SafeBaseUrlSchema = z.custom((value) => value instanceof URL && isSafeWebUrl(value), 'baseUrl must be a safe HTTPS or loopback HTTP URL');
-const AbsolutePathSchema = z.string().min(1).max(256).regex(/^\/(?:[^?#\s]*)$/, 'must be an absolute path without query, fragment, or whitespace');
-export class HostedHeartbeatDelegationRequestError extends Error {
-    status;
-    name = 'HostedHeartbeatDelegationRequestError';
-    constructor(status) {
-        super(`Heartbeat delegation failed with status ${status}.`);
-        this.status = status;
-    }
-}
-/** Authenticated coordinator client for one product-issued authority bundle. */
-export class HostedHeartbeatDelegationClient {
-    #endpoint;
-    #authorization;
-    #fetch;
-    constructor(config) {
-        const baseUrl = SafeBaseUrlSchema.parse(config.baseUrl);
-        this.#endpoint = new URL(AbsolutePathSchema.parse(config.path ?? HOSTED_HEARTBEAT_DELEGATIONS_PATH), baseUrl);
-        this.#authorization = `Bearer ${HostedHeartbeatServiceTokenSchema.parse(config.apiToken)}`;
-        this.#fetch = config.fetch ?? globalThis.fetch;
-    }
-    async issue(rawInput, signal) {
-        const input = HostedHeartbeatDelegationRequestSchema.parse(rawInput);
-        const response = await this.#fetch(this.#endpoint, {
-            method: 'POST',
-            headers: {
-                authorization: this.#authorization,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify(input),
-            redirect: 'error',
-            signal,
-        });
-        if (!response.ok) {
-            throw new HostedHeartbeatDelegationRequestError(response.status);
-        }
-        const delegation = HostedHeartbeatDelegationSchema.parse(await response.json());
-        if (delegation.taskId !== input.taskId
-            || delegation.executionId !== input.executionId) {
-            throw new Error('Product backend returned a mismatched heartbeat delegation.');
-        }
-        return delegation;
-    }
-}
-/** Executes a claimed task with the exact product-issued authority bundle. */
-export class HostedHeartbeatDelegatedExecutionTransport {
-    #config;
-    constructor(config) {
-        this.#config = config;
-    }
-    async execute(input) {
-        const delegation = await this.#config.delegations.issue({
-            schemaVersion: 1,
-            taskId: input.request.taskId,
-            executionId: input.request.executionId,
-        }, input.signal);
-        const service = new HostedHeartbeatTaskService({
-            authority: new DelegatedExecutionAuthorityIssuer(delegation),
-            executionHost: this.#config.executionHost,
-            modelCredentials: this.#config.modelCredentials,
-            mcp: {
-                allowedTools: delegation.authority.metadata.mcp.allowedTools,
-            },
-        });
-        const transport = new HostedHeartbeatAgentExecutionTransport({
-            runner: service,
-            resolveInvocationContext: () => ({
-                scope: delegation.scope,
-                runtimeSessionId: delegation.runtimeSessionId,
-                deadlineAt: delegation.deadlineAt,
-            }),
-        });
-        return await transport.execute(input);
-    }
-}
-/** Ensures downstream execution cannot widen a delegated authority bundle. */
-class DelegatedExecutionAuthorityIssuer {
-    delegation;
-    constructor(delegation) {
-        this.delegation = delegation;
-    }
-    async issue(input) {
-        const metadata = this.delegation.authority.metadata;
-        if (input.workflow !== HEARTBEAT_TASK_WORKFLOW
-            || input.workflow !== metadata.workflow
-            || input.invocationId !== metadata.invocationId
-            || input.runtimeSessionId !== metadata.runtimeSessionId
-            || !sameScope(input.scope, this.delegation.scope)
-            || !sameScope(input.scope, metadata.scope)
-            || !sameTools(input.mcp?.allowedTools, metadata.mcp.allowedTools)) {
-            throw new Error('Heartbeat delegation does not match Heddle execution.');
-        }
-        const authority = this.delegation.authority;
-        return Object.freeze({
-            metadata: metadata,
-            executionAssertion: () => authority.executionAssertion,
-            mcpCapability: () => authority.mcpCapability,
-            toJSON: () => metadata,
-        });
-    }
-}
-function sameScope(left, right) {
-    return left.tenantId === right.tenantId
-        && left.subjectId === right.subjectId
-        && left.productSessionId === right.productSessionId;
-}
-function sameTools(left, right) {
-    return Boolean(left
-        && left.length === right.length
-        && left.every((tool, index) => tool === right[index]));
-}
-//# sourceMappingURL=hosted-heartbeat-delegation-client.js.map

package/dist/coordinator/hosted-heartbeat-delegation-client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hosted-heartbeat-delegation-client.js","sourceRoot":"","sources":["../../src/coordinator/hosted-heartbeat-delegation-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,EACL,uBAAuB,EACvB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sCAAsC,EACtC,0BAA0B,GAE3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iCAAiC,EACjC,sCAAsC,EACtC,+BAA+B,GAGhC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAQvE,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAChC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,YAAY,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,EACtD,mDAAmD,CACpD,CAAC;AACF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CACzD,kBAAkB,EAClB,iEAAiE,CAClE,CAAC;AAEF,MAAM,OAAO,qCAAsC,SAAQ,KAAK;IAGzC;IAFZ,IAAI,GAAG,uCAAuC,CAAC;IAExD,YAAqB,MAAc;QACjC,KAAK,CAAC,2CAA2C,MAAM,GAAG,CAAC,CAAC;QADzC,WAAM,GAAN,MAAM,CAAQ;IAEnC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,+BAA+B;IAEjC,SAAS,CAAM;IACf,cAAc,CAAS;IACvB,MAAM,CAA0B;IAEzC,YAAY,MAA6C;QACvD,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,CACtB,kBAAkB,CAAC,KAAK,CACtB,MAAM,CAAC,IAAI,IAAI,iCAAiC,CACjD,EACD,OAAO,CACR,CAAC;QACF,IAAI,CAAC,cAAc,GAAG,UACpB,iCAAiC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CACzD,EAAE,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,KAAK,CACT,QAA0C,EAC1C,MAAoB;QAEpB,MAAM,KAAK,GAAG,sCAAsC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,cAAc;gBAClC,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC3B,QAAQ,EAAE,OAAO;YACjB,MAAM;SACP,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,qCAAqC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,UAAU,GAAG,+BAA+B,CAAC,KAAK,CACtD,MAAM,QAAQ,CAAC,IAAI,EAAE,CACtB,CAAC;QACF,IACE,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;eAC/B,UAAU,CAAC,WAAW,KAAK,KAAK,CAAC,WAAW,EAC/C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,6DAA6D,CAC9D,CAAC;QACJ,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,OAAO,0CAA0C;IAE5C,OAAO,CAAmD;IAEnE,YAAY,MAAwD;QAClE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,OAAO,CACX,KAAkD;QAElD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;YACtD,aAAa,EAAE,CAAC;YAChB,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;YAC5B,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW;SACvC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACjB,MAAM,OAAO,GAAG,IAAI,0BAA0B,CAAC;YAC7C,SAAS,EAAE,IAAI,iCAAiC,CAAC,UAAU,CAAC;YAC5D,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa;YACzC,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB;YAC/C,GAAG,EAAE;gBACH,YAAY,EAAE,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY;aAC7D;SACF,CAAC,CAAC;QACH,MAAM,SAAS,GAAG,IAAI,sCAAsC,CAAC;YAC3D,MAAM,EAAE,OAAO;YACf,wBAAwB,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC/B,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,UAAU,EAAE,UAAU,CAAC,UAAU;aAClC,CAAC;SACH,CAAC,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,iCAAiC;IACR;IAA7B,YAA6B,UAAqC;QAArC,eAAU,GAAV,UAAU,CAA2B;IAAG,CAAC;IAEtE,KAAK,CAAC,KAAK,CACT,KAAmC;QAEnC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC;QACpD,IACE,KAAK,CAAC,QAAQ,KAAK,uBAAuB;eACvC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;eACpC,KAAK,CAAC,YAAY,KAAK,QAAQ,CAAC,YAAY;eAC5C,KAAK,CAAC,gBAAgB,KAAK,QAAQ,CAAC,gBAAgB;eACpD,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;eAC9C,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC;eACvC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,EACjE,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAC5C,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,QAA4C;YACtD,kBAAkB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,kBAAkB;YACtD,aAAa,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,aAAa;YAC5C,MAAM,EAAE,GAAG,EAAE,CAAC,QAA4C;SAC3D,CAAC,CAAC;IACL,CAAC;CACF;AAED,SAAS,SAAS,CAChB,IAA2C,EAC3C,KAC+D;IAE/D,OAAO,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;WAClC,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;WAClC,IAAI,CAAC,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,CAAC;AACxD,CAAC;AAED,SAAS,SAAS,CAChB,IAAmC,EACnC,KAAwB;IAExB,OAAO,OAAO,CACZ,IAAI;WACD,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;WAC5B,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CACtD,CAAC;AACJ,CAAC","sourcesContent":["import { z } from 'zod';\nimport type {\n  ExecutionAuthorityIssueInput,\n  ExecutionAuthorityIssuer,\n  IssuedExecutionAuthority,\n  IssuedExecutionAuthorityMetadata,\n} from '../authority/index.js';\nimport {\n  HEARTBEAT_TASK_WORKFLOW,\n  isSafeWebUrl,\n} from '../contracts/index.js';\nimport {\n  HostedHeartbeatAgentExecutionTransport,\n  HostedHeartbeatTaskService,\n  type HostedHeartbeatAgentExecutionTransportInput,\n} from '../heartbeat/index.js';\nimport {\n  HOSTED_HEARTBEAT_DELEGATIONS_PATH,\n  HostedHeartbeatDelegationRequestSchema,\n  HostedHeartbeatDelegationSchema,\n  type HostedHeartbeatDelegation,\n  type HostedHeartbeatDelegationRequest,\n} from './contracts.js';\nimport { HostedHeartbeatServiceTokenSchema } from './service-token.js';\nimport type {\n  HostedHeartbeatDelegatedExecutionTransportConfig,\n  HostedHeartbeatDelegatedExecutionTransportPort,\n  HostedHeartbeatDelegationClientConfig,\n  HostedHeartbeatDelegationIssuer,\n} from './types.js';\n\nconst SafeBaseUrlSchema = z.custom<URL>(\n  (value) => value instanceof URL && isSafeWebUrl(value),\n  'baseUrl must be a safe HTTPS or loopback HTTP URL',\n);\nconst AbsolutePathSchema = z.string().min(1).max(256).regex(\n  /^\\/(?:[^?#\\s]*)$/,\n  'must be an absolute path without query, fragment, or whitespace',\n);\n\nexport class HostedHeartbeatDelegationRequestError extends Error {\n  readonly name = 'HostedHeartbeatDelegationRequestError';\n\n  constructor(readonly status: number) {\n    super(`Heartbeat delegation failed with status ${status}.`);\n  }\n}\n\n/** Authenticated coordinator client for one product-issued authority bundle. */\nexport class HostedHeartbeatDelegationClient\nimplements HostedHeartbeatDelegationIssuer {\n  readonly #endpoint: URL;\n  readonly #authorization: string;\n  readonly #fetch: typeof globalThis.fetch;\n\n  constructor(config: HostedHeartbeatDelegationClientConfig) {\n    const baseUrl = SafeBaseUrlSchema.parse(config.baseUrl);\n    this.#endpoint = new URL(\n      AbsolutePathSchema.parse(\n        config.path ?? HOSTED_HEARTBEAT_DELEGATIONS_PATH,\n      ),\n      baseUrl,\n    );\n    this.#authorization = `Bearer ${\n      HostedHeartbeatServiceTokenSchema.parse(config.apiToken)\n    }`;\n    this.#fetch = config.fetch ?? globalThis.fetch;\n  }\n\n  async issue(\n    rawInput: HostedHeartbeatDelegationRequest,\n    signal?: AbortSignal,\n  ): Promise<HostedHeartbeatDelegation> {\n    const input = HostedHeartbeatDelegationRequestSchema.parse(rawInput);\n    const response = await this.#fetch(this.#endpoint, {\n      method: 'POST',\n      headers: {\n        authorization: this.#authorization,\n        'content-type': 'application/json',\n      },\n      body: JSON.stringify(input),\n      redirect: 'error',\n      signal,\n    });\n    if (!response.ok) {\n      throw new HostedHeartbeatDelegationRequestError(response.status);\n    }\n    const delegation = HostedHeartbeatDelegationSchema.parse(\n      await response.json(),\n    );\n    if (\n      delegation.taskId !== input.taskId\n      || delegation.executionId !== input.executionId\n    ) {\n      throw new Error(\n        'Product backend returned a mismatched heartbeat delegation.',\n      );\n    }\n    return delegation;\n  }\n}\n\n/** Executes a claimed task with the exact product-issued authority bundle. */\nexport class HostedHeartbeatDelegatedExecutionTransport\nimplements HostedHeartbeatDelegatedExecutionTransportPort {\n  readonly #config: HostedHeartbeatDelegatedExecutionTransportConfig;\n\n  constructor(config: HostedHeartbeatDelegatedExecutionTransportConfig) {\n    this.#config = config;\n  }\n\n  async execute(\n    input: HostedHeartbeatAgentExecutionTransportInput,\n  ): Promise<unknown> {\n    const delegation = await this.#config.delegations.issue({\n      schemaVersion: 1,\n      taskId: input.request.taskId,\n      executionId: input.request.executionId,\n    }, input.signal);\n    const service = new HostedHeartbeatTaskService({\n      authority: new DelegatedExecutionAuthorityIssuer(delegation),\n      executionHost: this.#config.executionHost,\n      modelCredentials: this.#config.modelCredentials,\n      mcp: {\n        allowedTools: delegation.authority.metadata.mcp.allowedTools,\n      },\n    });\n    const transport = new HostedHeartbeatAgentExecutionTransport({\n      runner: service,\n      resolveInvocationContext: () => ({\n        scope: delegation.scope,\n        runtimeSessionId: delegation.runtimeSessionId,\n        deadlineAt: delegation.deadlineAt,\n      }),\n    });\n    return await transport.execute(input);\n  }\n}\n\n/** Ensures downstream execution cannot widen a delegated authority bundle. */\nclass DelegatedExecutionAuthorityIssuer implements ExecutionAuthorityIssuer {\n  constructor(private readonly delegation: HostedHeartbeatDelegation) {}\n\n  async issue(\n    input: ExecutionAuthorityIssueInput,\n  ): Promise<IssuedExecutionAuthority> {\n    const metadata = this.delegation.authority.metadata;\n    if (\n      input.workflow !== HEARTBEAT_TASK_WORKFLOW\n      || input.workflow !== metadata.workflow\n      || input.invocationId !== metadata.invocationId\n      || input.runtimeSessionId !== metadata.runtimeSessionId\n      || !sameScope(input.scope, this.delegation.scope)\n      || !sameScope(input.scope, metadata.scope)\n      || !sameTools(input.mcp?.allowedTools, metadata.mcp.allowedTools)\n    ) {\n      throw new Error('Heartbeat delegation does not match Heddle execution.');\n    }\n    const authority = this.delegation.authority;\n    return Object.freeze({\n      metadata: metadata as IssuedExecutionAuthorityMetadata,\n      executionAssertion: () => authority.executionAssertion,\n      mcpCapability: () => authority.mcpCapability,\n      toJSON: () => metadata as IssuedExecutionAuthorityMetadata,\n    });\n  }\n}\n\nfunction sameScope(\n  left: ExecutionAuthorityIssueInput['scope'],\n  right: HostedHeartbeatDelegation['scope']\n    | HostedHeartbeatDelegation['authority']['metadata']['scope'],\n): boolean {\n  return left.tenantId === right.tenantId\n    && left.subjectId === right.subjectId\n    && left.productSessionId === right.productSessionId;\n}\n\nfunction sameTools(\n  left: readonly string[] | undefined,\n  right: readonly string[],\n): boolean {\n  return Boolean(\n    left\n    && left.length === right.length\n    && left.every((tool, index) => tool === right[index]),\n  );\n}\n"]}

package/dist/coordinator/hosted-heartbeat-delegation-service.d.ts

@@ -1,15 +0,0 @@
-import { type HostedHeartbeatDelegation, type HostedHeartbeatDelegationRequest } from './contracts.js';
-import type { HostedHeartbeatDelegationIssuer, HostedHeartbeatDelegationServiceConfig } from './types.js';
-export declare class HostedHeartbeatDelegationRejectedError extends Error {
-    readonly name = "HostedHeartbeatDelegationRejectedError";
-}
-/**
- * Converts one product authorization decision into a fully bound Heddle
- * authority bundle. Product code never constructs the delegation wire shape.
- */
-export declare class HostedHeartbeatDelegationService implements HostedHeartbeatDelegationIssuer {
-    #private;
-    constructor(config: HostedHeartbeatDelegationServiceConfig);
-    issue(rawInput: HostedHeartbeatDelegationRequest, rawSignal?: AbortSignal): Promise<HostedHeartbeatDelegation>;
-}
-//# sourceMappingURL=hosted-heartbeat-delegation-service.d.ts.map

package/dist/coordinator/hosted-heartbeat-delegation-service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hosted-heartbeat-delegation-service.d.ts","sourceRoot":"","sources":["../../src/coordinator/hosted-heartbeat-delegation-service.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACtC,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EACV,+BAA+B,EAC/B,sCAAsC,EACvC,MAAM,YAAY,CAAC;AAOpB,qBAAa,sCAAuC,SAAQ,KAAK;IAC/D,QAAQ,CAAC,IAAI,4CAA4C;CAC1D;AAED;;;GAGG;AACH,qBAAa,gCACb,YAAW,+BAA+B;;gBAO5B,MAAM,EAAE,sCAAsC;IAYpD,KAAK,CACT,QAAQ,EAAE,gCAAgC,EAC1C,SAAS,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,yBAAyB,CAAC;CAqDtC"}

package/dist/coordinator/hosted-heartbeat-delegation-service.js

@@ -1,81 +0,0 @@
-import dayjs from 'dayjs';
-import { z } from 'zod';
-import { HEARTBEAT_TASK_WORKFLOW, OpaqueIdSchema } from '../contracts/index.js';
-import { HostedHeartbeatDelegationAuthorizationSchema, HostedHeartbeatDelegationRequestSchema, HostedHeartbeatDelegationSchema, } from './contracts.js';
-import { createHostedRuntimeSessionId } from './runtime-session.js';
-const DelegationServiceConfigSchema = z.object({
-    runtimeSessionNamespace: OpaqueIdSchema,
-    maxExecutionMs: z.number().int().min(1_000).max(Number.MAX_SAFE_INTEGER),
-}).strict();
-export class HostedHeartbeatDelegationRejectedError extends Error {
-    name = 'HostedHeartbeatDelegationRejectedError';
-}
-/**
- * Converts one product authorization decision into a fully bound Heddle
- * authority bundle. Product code never constructs the delegation wire shape.
- */
-export class HostedHeartbeatDelegationService {
-    #authority;
-    #authorizer;
-    #runtimeSessionNamespace;
-    #maxExecutionMs;
-    #now;
-    constructor(config) {
-        const parsed = DelegationServiceConfigSchema.parse({
-            runtimeSessionNamespace: config.runtimeSessionNamespace,
-            maxExecutionMs: config.maxExecutionMs,
-        });
-        this.#authority = config.authority;
-        this.#authorizer = config.authorizer;
-        this.#runtimeSessionNamespace = parsed.runtimeSessionNamespace;
-        this.#maxExecutionMs = parsed.maxExecutionMs;
-        this.#now = config.now ?? (() => new Date());
-    }
-    async issue(rawInput, rawSignal) {
-        const input = HostedHeartbeatDelegationRequestSchema.parse(rawInput);
-        const signal = rawSignal ?? new AbortController().signal;
-        signal.throwIfAborted();
-        const rawAuthorization = await this.#authorizer.authorize({
-            taskId: input.taskId,
-            executionId: input.executionId,
-            signal,
-        });
-        if (!rawAuthorization) {
-            throw new HostedHeartbeatDelegationRejectedError('The product rejected this heartbeat execution.');
-        }
-        const authorization = HostedHeartbeatDelegationAuthorizationSchema.parse(rawAuthorization);
-        const runtimeSessionId = createHostedRuntimeSessionId({
-            namespace: this.#runtimeSessionNamespace,
-            scope: authorization.scope,
-        });
-        const deadlineAt = dayjs(this.#now())
-            .add(this.#maxExecutionMs, 'millisecond')
-            .toISOString();
-        const issued = await this.#authority.issue({
-            scope: authorization.scope,
-            runtimeSessionId,
-            invocationId: input.executionId,
-            workflow: HEARTBEAT_TASK_WORKFLOW,
-            mcp: { allowedTools: authorization.allowedTools },
-        });
-        signal.throwIfAborted();
-        const mcpCapability = issued.mcpCapability();
-        if (!mcpCapability || !issued.metadata.mcp) {
-            throw new Error('Hosted heartbeat delegation requires an MCP-capable execution authority.');
-        }
-        return HostedHeartbeatDelegationSchema.parse({
-            schemaVersion: 1,
-            taskId: input.taskId,
-            executionId: input.executionId,
-            scope: authorization.scope,
-            runtimeSessionId,
-            deadlineAt,
-            authority: {
-                metadata: issued.metadata,
-                executionAssertion: issued.executionAssertion(),
-                mcpCapability,
-            },
-        });
-    }
-}
-//# sourceMappingURL=hosted-heartbeat-delegation-service.js.map

package/dist/coordinator/hosted-heartbeat-delegation-service.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hosted-heartbeat-delegation-service.js","sourceRoot":"","sources":["../../src/coordinator/hosted-heartbeat-delegation-service.ts"],"names":[],"mappings":"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","sourcesContent":["import dayjs from 'dayjs';\nimport { z } from 'zod';\nimport { HEARTBEAT_TASK_WORKFLOW, OpaqueIdSchema } from '../contracts/index.js';\nimport {\n  HostedHeartbeatDelegationAuthorizationSchema,\n  HostedHeartbeatDelegationRequestSchema,\n  HostedHeartbeatDelegationSchema,\n  type HostedHeartbeatDelegation,\n  type HostedHeartbeatDelegationRequest,\n} from './contracts.js';\nimport { createHostedRuntimeSessionId } from './runtime-session.js';\nimport type {\n  HostedHeartbeatDelegationIssuer,\n  HostedHeartbeatDelegationServiceConfig,\n} from './types.js';\n\nconst DelegationServiceConfigSchema = z.object({\n  runtimeSessionNamespace: OpaqueIdSchema,\n  maxExecutionMs: z.number().int().min(1_000).max(Number.MAX_SAFE_INTEGER),\n}).strict();\n\nexport class HostedHeartbeatDelegationRejectedError extends Error {\n  readonly name = 'HostedHeartbeatDelegationRejectedError';\n}\n\n/**\n * Converts one product authorization decision into a fully bound Heddle\n * authority bundle. Product code never constructs the delegation wire shape.\n */\nexport class HostedHeartbeatDelegationService\nimplements HostedHeartbeatDelegationIssuer {\n  readonly #authority: HostedHeartbeatDelegationServiceConfig['authority'];\n  readonly #authorizer: HostedHeartbeatDelegationServiceConfig['authorizer'];\n  readonly #runtimeSessionNamespace: string;\n  readonly #maxExecutionMs: number;\n  readonly #now: () => Date;\n\n  constructor(config: HostedHeartbeatDelegationServiceConfig) {\n    const parsed = DelegationServiceConfigSchema.parse({\n      runtimeSessionNamespace: config.runtimeSessionNamespace,\n      maxExecutionMs: config.maxExecutionMs,\n    });\n    this.#authority = config.authority;\n    this.#authorizer = config.authorizer;\n    this.#runtimeSessionNamespace = parsed.runtimeSessionNamespace;\n    this.#maxExecutionMs = parsed.maxExecutionMs;\n    this.#now = config.now ?? (() => new Date());\n  }\n\n  async issue(\n    rawInput: HostedHeartbeatDelegationRequest,\n    rawSignal?: AbortSignal,\n  ): Promise<HostedHeartbeatDelegation> {\n    const input = HostedHeartbeatDelegationRequestSchema.parse(rawInput);\n    const signal = rawSignal ?? new AbortController().signal;\n    signal.throwIfAborted();\n    const rawAuthorization = await this.#authorizer.authorize({\n      taskId: input.taskId,\n      executionId: input.executionId,\n      signal,\n    });\n    if (!rawAuthorization) {\n      throw new HostedHeartbeatDelegationRejectedError(\n        'The product rejected this heartbeat execution.',\n      );\n    }\n    const authorization = HostedHeartbeatDelegationAuthorizationSchema.parse(\n      rawAuthorization,\n    );\n    const runtimeSessionId = createHostedRuntimeSessionId({\n      namespace: this.#runtimeSessionNamespace,\n      scope: authorization.scope,\n    });\n    const deadlineAt = dayjs(this.#now())\n      .add(this.#maxExecutionMs, 'millisecond')\n      .toISOString();\n    const issued = await this.#authority.issue({\n      scope: authorization.scope,\n      runtimeSessionId,\n      invocationId: input.executionId,\n      workflow: HEARTBEAT_TASK_WORKFLOW,\n      mcp: { allowedTools: authorization.allowedTools },\n    });\n    signal.throwIfAborted();\n    const mcpCapability = issued.mcpCapability();\n    if (!mcpCapability || !issued.metadata.mcp) {\n      throw new Error(\n        'Hosted heartbeat delegation requires an MCP-capable execution authority.',\n      );\n    }\n\n    return HostedHeartbeatDelegationSchema.parse({\n      schemaVersion: 1,\n      taskId: input.taskId,\n      executionId: input.executionId,\n      scope: authorization.scope,\n      runtimeSessionId,\n      deadlineAt,\n      authority: {\n        metadata: issued.metadata,\n        executionAssertion: issued.executionAssertion(),\n        mcpCapability,\n      },\n    });\n  }\n}\n"]}