@xemahq/agent-session-runtime 0.11.1 → 0.11.2

package/src/lib/launch-identity/canonical-contract.ts

@@ -1,352 +0,0 @@
-import { canonicalJson, stableHash } from '@xemahq/declarative-reconciler';
-import { Sha256HexSchema } from '@xemahq/kernel-contracts/content-address';
-
-export type CanonicalJsonValue =
-  | boolean
-  | number
-  | string
-  | null
-  | readonly CanonicalJsonValue[]
-  | { readonly [key: string]: CanonicalJsonValue };
-
-export interface ResourceBindingRef {
-  readonly kind: string;
-  readonly ref: string;
-}
-
-/**
- * OCI immutable-digest prefix. The digest BODY is validated by the canonical
- * {@link Sha256HexSchema} rather than a local `[a-f0-9]{64}` copy, so this
- * package holds no SHA-256 grammar of its own.
- */
-const IMAGE_DIGEST_PREFIX = 'sha256:';
-
-const SECRET_FIELD_PATTERN =
-  /(?:^|[_-])(api[_-]?key|authorization|cookie|credential|password|private[_-]?key|secret|token)(?:$|[_-])/iu;
-const SECRET_CAMEL_CASE_PATTERN =
-  /(?:apiKey|authorization|cookie|credential|password|privateKey|secret|token)/u;
-const SECRET_REFERENCE_SUFFIX_PATTERN = /Refs?$/u;
-
-export function canonicalContractJson(value: unknown): string {
-  return canonicalJson(value);
-}
-
-export function hashCanonicalContract(value: unknown): string {
-  return stableHash(value);
-}
-
-export function requireExactObject(
-  value: unknown,
-  path: string,
-  requiredKeys: readonly string[],
-  optionalKeys: readonly string[] = [],
-): Readonly<Record<string, unknown>> {
-  if (!isPlainObject(value)) {
-    throw new TypeError(`${path} must be a plain object.`);
-  }
-
-  const allowedKeys = new Set([...requiredKeys, ...optionalKeys]);
-  for (const key of Object.keys(value)) {
-    if (!allowedKeys.has(key)) {
-      throw new TypeError(`${path}.${key} is not a supported field.`);
-    }
-  }
-
-  for (const key of requiredKeys) {
-    if (!Object.hasOwn(value, key)) {
-      throw new TypeError(`${path}.${key} is required.`);
-    }
-  }
-
-  return value;
-}
-
-export function requireNonEmptyString(value: unknown, path: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new TypeError(`${path} must be a non-empty string.`);
-  }
-  return value;
-}
-
-export function requireBoolean(value: unknown, path: string): boolean {
-  if (typeof value !== 'boolean') {
-    throw new TypeError(`${path} must be a boolean.`);
-  }
-  return value;
-}
-
-export function requireSha256(value: unknown, path: string): string {
-  const hash = requireNonEmptyString(value, path);
-  if (!Sha256HexSchema.safeParse(hash).success) {
-    throw new TypeError(`${path} must be a lowercase SHA-256 hex digest.`);
-  }
-  return hash;
-}
-
-/**
- * Validates an OCI IMMUTABLE image reference — `sha256:<64 lowercase hex>`.
- *
- * The single site for this rule. It was previously spelled as an identical
- * `IMAGE_DIGEST_PATTERN` regex in both `runtime-template-key.ts` and
- * `compiled-session-launch-plan.ts`; two copies of a security-relevant
- * "is this reference immutable" check can drift, and each was also a private
- * restatement of the SHA-256 grammar that `@xemahq/kernel-contracts
- * /content-address` now owns canonically.
- */
-export function requireImageDigest(value: unknown, path: string): string {
-  const digest = requireNonEmptyString(value, path);
-  if (!digest.startsWith(IMAGE_DIGEST_PREFIX)) {
-    throw new TypeError(
-      `${path} must be an immutable sha256 image digest.`,
-    );
-  }
-  if (
-    !Sha256HexSchema.safeParse(digest.slice(IMAGE_DIGEST_PREFIX.length)).success
-  ) {
-    throw new TypeError(
-      `${path} must be an immutable sha256 image digest.`,
-    );
-  }
-  return digest;
-}
-
-export function requireNonNegativeSafeInteger(
-  value: unknown,
-  path: string,
-): number {
-  if (!Number.isSafeInteger(value) || (value as number) < 0) {
-    throw new TypeError(`${path} must be a non-negative safe integer.`);
-  }
-  return value as number;
-}
-
-export function requireEnumValue<T extends string>(
-  value: unknown,
-  path: string,
-  values: readonly T[],
-): T {
-  if (typeof value !== 'string' || !values.includes(value as T)) {
-    throw new TypeError(
-      `${path} must be one of: ${values.map((entry) => `'${entry}'`).join(', ')}.`,
-    );
-  }
-  return value as T;
-}
-
-export function requireStringRefs(
-  value: unknown,
-  path: string,
-): readonly string[] {
-  if (!Array.isArray(value)) {
-    throw new TypeError(`${path} must be an array.`);
-  }
-
-  return Object.freeze(
-    [
-      ...new Set(
-        value.map((entry, index) =>
-          requireNonEmptyString(entry, `${path}[${index}]`),
-        ),
-      ),
-    ].sort(),
-  );
-}
-
-export function requireResourceBindingRefs(
-  value: unknown,
-  path: string,
-): readonly ResourceBindingRef[] {
-  if (!Array.isArray(value)) {
-    throw new TypeError(`${path} must be an array.`);
-  }
-
-  const refs = value.map((entry, index) => {
-    const entryPath = `${path}[${index}]`;
-    const object = requireExactObject(entry, entryPath, ['kind', 'ref']);
-    return Object.freeze({
-      kind: requireNonEmptyString(object.kind, `${entryPath}.kind`),
-      ref: requireNonEmptyString(object.ref, `${entryPath}.ref`),
-    });
-  });
-
-  const byCanonicalRef = new Map(
-    refs.map((entry) => [canonicalJson(entry), entry] as const),
-  );
-  return Object.freeze(
-    [...byCanonicalRef.entries()]
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([, entry]) => entry),
-  );
-}
-
-export function requireSecretFreeJsonObject(
-  value: unknown,
-  path: string,
-): Readonly<Record<string, CanonicalJsonValue>> {
-  const normalized = normalizeCanonicalJson(value, path, true);
-  if (
-    normalized === null ||
-    Array.isArray(normalized) ||
-    typeof normalized !== 'object'
-  ) {
-    throw new TypeError(`${path} must be a plain JSON object.`);
-  }
-  return normalized as Readonly<Record<string, CanonicalJsonValue>>;
-}
-
-export function requireCanonicalJsonObject(
-  value: unknown,
-  path: string,
-): Readonly<Record<string, CanonicalJsonValue>> {
-  const normalized = normalizeCanonicalJson(value, path, false);
-  if (
-    normalized === null ||
-    Array.isArray(normalized) ||
-    typeof normalized !== 'object'
-  ) {
-    throw new TypeError(`${path} must be a plain JSON object.`);
-  }
-  return normalized as Readonly<Record<string, CanonicalJsonValue>>;
-}
-
-export function assertNoTenantOrSecretTemplateFields(
-  value: unknown,
-  path: string,
-): void {
-  const visited = new Set<object>();
-
-  function inspect(current: unknown, currentPath: string): void {
-    if (current === null || typeof current !== 'object') {
-      return;
-    }
-    if (visited.has(current)) {
-      throw new TypeError(`${currentPath} must not contain cycles.`);
-    }
-    visited.add(current);
-
-    if (Array.isArray(current)) {
-      current.forEach((entry, index) =>
-        inspect(entry, `${currentPath}[${index}]`),
-      );
-      return;
-    }
-    if (!isPlainObject(current)) {
-      throw new TypeError(`${currentPath} must contain only plain objects.`);
-    }
-
-    for (const [key, entry] of Object.entries(current)) {
-      if (isTenantField(key) || isSecretField(key)) {
-        throw new TypeError(
-          `${currentPath}.${key} is tenant/session/secret state and cannot enter a RuntimeTemplateKey.`,
-        );
-      }
-      inspect(entry, `${currentPath}.${key}`);
-    }
-  }
-
-  inspect(value, path);
-}
-
-function normalizeCanonicalJson(
-  value: unknown,
-  path: string,
-  rejectSecretFields: boolean,
-  visited = new Set<object>(),
-): CanonicalJsonValue {
-  if (
-    value === null ||
-    typeof value === 'string' ||
-    typeof value === 'boolean'
-  ) {
-    return value;
-  }
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) {
-      throw new TypeError(`${path} must contain only finite numbers.`);
-    }
-    return value;
-  }
-  if (typeof value !== 'object') {
-    throw new TypeError(`${path} must contain only JSON values.`);
-  }
-  if (visited.has(value)) {
-    throw new TypeError(`${path} must not contain cycles.`);
-  }
-  visited.add(value);
-
-  if (Array.isArray(value)) {
-    const normalized = value.map((entry, index) =>
-      normalizeCanonicalJson(
-        entry,
-        `${path}[${index}]`,
-        rejectSecretFields,
-        visited,
-      ),
-    );
-    visited.delete(value);
-    return Object.freeze(normalized);
-  }
-  if (!isPlainObject(value)) {
-    throw new TypeError(`${path} must contain only plain JSON objects.`);
-  }
-
-  const normalized: Record<string, CanonicalJsonValue> = {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (
-      rejectSecretFields &&
-      isSecretField(key) &&
-      !SECRET_REFERENCE_SUFFIX_PATTERN.test(key)
-    ) {
-      throw new TypeError(
-        `${path}.${key} appears to contain secret material; pass an opaque reference ending in Ref or Refs instead.`,
-      );
-    }
-    normalized[key] = normalizeCanonicalJson(
-      entry,
-      `${path}.${key}`,
-      rejectSecretFields,
-      visited,
-    );
-  }
-  visited.delete(value);
-  return Object.freeze(normalized);
-}
-
-function isTenantField(key: string): boolean {
-  const normalized = key.replaceAll(/[_-]/gu, '').toLowerCase();
-  return [
-    'binding',
-    'context',
-    'domain',
-    'domainid',
-    'input',
-    'organization',
-    'organizationid',
-    'org',
-    'orgid',
-    'project',
-    'projectid',
-    'session',
-    'sessionid',
-    'tenant',
-    'tenantid',
-    'thread',
-    'threadid',
-    'user',
-    'userid',
-  ].includes(normalized);
-}
-
-function isSecretField(key: string): boolean {
-  return SECRET_FIELD_PATTERN.test(key) || SECRET_CAMEL_CASE_PATTERN.test(key);
-}
-
-function isPlainObject(
-  value: unknown,
-): value is Readonly<Record<string, unknown>> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}

package/src/lib/launch-identity/index.ts

@@ -1,4 +0,0 @@
-export * from './canonical-contract';
-export * from './runtime-template-key';
-export * from './session-binding';
-export * from './thread-reuse-key';

package/src/lib/launch-identity/runtime-template-key.ts

@@ -1,143 +0,0 @@
-import {
-  assertNoTenantOrSecretTemplateFields,
-  canonicalContractJson,
-  hashCanonicalContract,
-  requireEnumValue,
-  requireExactObject,
-  requireImageDigest,
-  requireNonEmptyString,
-  requireSha256,
-} from './canonical-contract';
-
-export enum RuntimeTemplateTenantDependency {
-  OrganizationNeutral = 'organization-neutral',
-  OrganizationBound = 'organization-bound',
-}
-
-export enum RuntimeTemplateTrustPolicy {
-  Shared = 'shared',
-  Dedicated = 'dedicated',
-  Confidential = 'confidential',
-}
-
-export interface RuntimeTemplateKey {
-  readonly schemaVersion: 1;
-  readonly tenantDependency: RuntimeTemplateTenantDependency;
-  readonly trustPolicy: RuntimeTemplateTrustPolicy;
-  readonly runtimeRef: string;
-  readonly runtimeRevision: string;
-  readonly imageDigest: string;
-  readonly agentRevision: string;
-  readonly primaryAgentHash: string;
-  readonly subagentsHash: string;
-  readonly skillsHash: string;
-  readonly toolsHash: string;
-  readonly capabilityDescriptorsHash: string;
-  readonly mcpDescriptorsHash: string;
-  readonly workspacePlanHash: string;
-  readonly layoutProfile: string;
-}
-
-const REQUIRED_KEYS = [
-  'schemaVersion',
-  'tenantDependency',
-  'trustPolicy',
-  'runtimeRef',
-  'runtimeRevision',
-  'imageDigest',
-  'agentRevision',
-  'primaryAgentHash',
-  'subagentsHash',
-  'skillsHash',
-  'toolsHash',
-  'capabilityDescriptorsHash',
-  'mcpDescriptorsHash',
-  'workspacePlanHash',
-  'layoutProfile',
-] as const;
-
-const TENANT_DEPENDENCIES = Object.values(RuntimeTemplateTenantDependency);
-const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
-
-/**
- * Validates and canonicalizes the immutable execution dimensions used to
- * select warm compute. Tenant, invocation and credential data have no valid
- * slot in this contract and are rejected even when supplied as extra fields.
- */
-export function createRuntimeTemplateKey(input: unknown): RuntimeTemplateKey {
-  assertNoTenantOrSecretTemplateFields(input, 'RuntimeTemplateKey');
-  const object = requireExactObject(input, 'RuntimeTemplateKey', REQUIRED_KEYS);
-
-  if (object.schemaVersion !== 1) {
-    throw new TypeError('RuntimeTemplateKey.schemaVersion must be 1.');
-  }
-
-  const imageDigest = requireImageDigest(
-    object.imageDigest,
-    'RuntimeTemplateKey.imageDigest',
-  );
-
-  return Object.freeze({
-    schemaVersion: 1,
-    tenantDependency: requireEnumValue(
-      object.tenantDependency,
-      'RuntimeTemplateKey.tenantDependency',
-      TENANT_DEPENDENCIES,
-    ),
-    trustPolicy: requireEnumValue(
-      object.trustPolicy,
-      'RuntimeTemplateKey.trustPolicy',
-      TRUST_POLICIES,
-    ),
-    runtimeRef: requireNonEmptyString(
-      object.runtimeRef,
-      'RuntimeTemplateKey.runtimeRef',
-    ),
-    runtimeRevision: requireNonEmptyString(
-      object.runtimeRevision,
-      'RuntimeTemplateKey.runtimeRevision',
-    ),
-    imageDigest,
-    agentRevision: requireNonEmptyString(
-      object.agentRevision,
-      'RuntimeTemplateKey.agentRevision',
-    ),
-    primaryAgentHash: requireSha256(
-      object.primaryAgentHash,
-      'RuntimeTemplateKey.primaryAgentHash',
-    ),
-    subagentsHash: requireSha256(
-      object.subagentsHash,
-      'RuntimeTemplateKey.subagentsHash',
-    ),
-    skillsHash: requireSha256(
-      object.skillsHash,
-      'RuntimeTemplateKey.skillsHash',
-    ),
-    toolsHash: requireSha256(object.toolsHash, 'RuntimeTemplateKey.toolsHash'),
-    capabilityDescriptorsHash: requireSha256(
-      object.capabilityDescriptorsHash,
-      'RuntimeTemplateKey.capabilityDescriptorsHash',
-    ),
-    mcpDescriptorsHash: requireSha256(
-      object.mcpDescriptorsHash,
-      'RuntimeTemplateKey.mcpDescriptorsHash',
-    ),
-    workspacePlanHash: requireSha256(
-      object.workspacePlanHash,
-      'RuntimeTemplateKey.workspacePlanHash',
-    ),
-    layoutProfile: requireNonEmptyString(
-      object.layoutProfile,
-      'RuntimeTemplateKey.layoutProfile',
-    ),
-  });
-}
-
-export function serializeRuntimeTemplateKey(input: RuntimeTemplateKey): string {
-  return canonicalContractJson(createRuntimeTemplateKey(input));
-}
-
-export function hashRuntimeTemplateKey(input: RuntimeTemplateKey): string {
-  return hashCanonicalContract(createRuntimeTemplateKey(input));
-}

package/src/lib/launch-identity/session-binding.ts

@@ -1,152 +0,0 @@
-import {
-  canonicalContractJson,
-  type CanonicalJsonValue,
-  hashCanonicalContract,
-  type ResourceBindingRef,
-  requireExactObject,
-  requireNonEmptyString,
-  requireNonNegativeSafeInteger,
-  requireResourceBindingRefs,
-  requireSecretFreeJsonObject,
-  requireStringRefs,
-} from './canonical-contract';
-
-export interface SessionBinding {
-  readonly schemaVersion: 1;
-  readonly sessionId: string;
-  readonly organizationId: string;
-  readonly projectId: string;
-  readonly userId: string;
-  readonly domainRefs: readonly ResourceBindingRef[];
-  readonly storageAllocationRef: string;
-  readonly workingFileSourceRefs: readonly string[];
-  readonly outputRouteRef: string;
-  readonly actorTokenRef?: string;
-  readonly serviceTokenRef?: string;
-  readonly providerTokenRefs: readonly string[];
-  readonly credentialGrantRefs: readonly string[];
-  readonly databaseGrantRefs: readonly string[];
-  readonly dynamicContext: Readonly<Record<string, CanonicalJsonValue>>;
-  readonly bindingRevision: string;
-  readonly bindingEpoch: number;
-}
-
-const REQUIRED_KEYS = [
-  'schemaVersion',
-  'sessionId',
-  'organizationId',
-  'projectId',
-  'userId',
-  'domainRefs',
-  'storageAllocationRef',
-  'workingFileSourceRefs',
-  'outputRouteRef',
-  'providerTokenRefs',
-  'credentialGrantRefs',
-  'databaseGrantRefs',
-  'dynamicContext',
-  'bindingRevision',
-  'bindingEpoch',
-] as const;
-
-const OPTIONAL_KEYS = ['actorTokenRef', 'serviceTokenRef'] as const;
-
-/**
- * Canonical tenant/session state applied atomically after a runtime claim.
- * Credentials are represented only by opaque refs; raw secrets are rejected
- * from dynamicContext.
- */
-export function createSessionBinding(input: unknown): SessionBinding {
-  const object = requireExactObject(
-    input,
-    'SessionBinding',
-    REQUIRED_KEYS,
-    OPTIONAL_KEYS,
-  );
-
-  if (object.schemaVersion !== 1) {
-    throw new TypeError('SessionBinding.schemaVersion must be 1.');
-  }
-
-  const actorTokenRef =
-    object.actorTokenRef === undefined
-      ? undefined
-      : requireNonEmptyString(
-          object.actorTokenRef,
-          'SessionBinding.actorTokenRef',
-        );
-  const serviceTokenRef =
-    object.serviceTokenRef === undefined
-      ? undefined
-      : requireNonEmptyString(
-          object.serviceTokenRef,
-          'SessionBinding.serviceTokenRef',
-        );
-
-  return Object.freeze({
-    schemaVersion: 1,
-    sessionId: requireNonEmptyString(
-      object.sessionId,
-      'SessionBinding.sessionId',
-    ),
-    organizationId: requireNonEmptyString(
-      object.organizationId,
-      'SessionBinding.organizationId',
-    ),
-    projectId: requireNonEmptyString(
-      object.projectId,
-      'SessionBinding.projectId',
-    ),
-    userId: requireNonEmptyString(object.userId, 'SessionBinding.userId'),
-    domainRefs: requireResourceBindingRefs(
-      object.domainRefs,
-      'SessionBinding.domainRefs',
-    ),
-    storageAllocationRef: requireNonEmptyString(
-      object.storageAllocationRef,
-      'SessionBinding.storageAllocationRef',
-    ),
-    workingFileSourceRefs: requireStringRefs(
-      object.workingFileSourceRefs,
-      'SessionBinding.workingFileSourceRefs',
-    ),
-    outputRouteRef: requireNonEmptyString(
-      object.outputRouteRef,
-      'SessionBinding.outputRouteRef',
-    ),
-    ...(actorTokenRef === undefined ? {} : { actorTokenRef }),
-    ...(serviceTokenRef === undefined ? {} : { serviceTokenRef }),
-    providerTokenRefs: requireStringRefs(
-      object.providerTokenRefs,
-      'SessionBinding.providerTokenRefs',
-    ),
-    credentialGrantRefs: requireStringRefs(
-      object.credentialGrantRefs,
-      'SessionBinding.credentialGrantRefs',
-    ),
-    databaseGrantRefs: requireStringRefs(
-      object.databaseGrantRefs,
-      'SessionBinding.databaseGrantRefs',
-    ),
-    dynamicContext: requireSecretFreeJsonObject(
-      object.dynamicContext,
-      'SessionBinding.dynamicContext',
-    ),
-    bindingRevision: requireNonEmptyString(
-      object.bindingRevision,
-      'SessionBinding.bindingRevision',
-    ),
-    bindingEpoch: requireNonNegativeSafeInteger(
-      object.bindingEpoch,
-      'SessionBinding.bindingEpoch',
-    ),
-  });
-}
-
-export function serializeSessionBinding(input: SessionBinding): string {
-  return canonicalContractJson(createSessionBinding(input));
-}
-
-export function hashSessionBinding(input: SessionBinding): string {
-  return hashCanonicalContract(createSessionBinding(input));
-}