codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14

package/src/credential-output.ts

@@ -0,0 +1,89 @@
+const CREDENTIAL_FIELD_NAMES = new Set(['token', 'writerToken', 'claimToken']);
+
+export interface CredentialOutputAllowance {
+  path: string;
+}
+
+export class UnsafeCredentialOutputError extends Error {
+  readonly paths: string[];
+
+  constructor(paths: string[]) {
+    super('CLI output contained credentials outside an exact issuance receipt allowance.');
+    this.name = 'UnsafeCredentialOutputError';
+    this.paths = [...new Set(paths)].sort();
+  }
+}
+
+export function assertCliSuccessCredentialSafety(
+  value: unknown,
+  allowances: readonly CredentialOutputAllowance[],
+  sensitiveInputs: readonly string[],
+): void {
+  const allowedPaths = new Set(allowances.map((allowance) => allowance.path));
+  const secrets = new Set(sensitiveInputs.filter(Boolean));
+  const violations: string[] = [];
+  visit(value, '$', (path, key, candidate) => {
+    const credentialField = key !== null
+      && CREDENTIAL_FIELD_NAMES.has(key)
+      && candidate !== null
+      && candidate !== undefined;
+    const containingSecrets = typeof candidate === 'string'
+      ? [...secrets].filter((secret) => candidate.includes(secret))
+      : [];
+    const exactAllowedIssuanceValue = credentialField
+      && allowedPaths.has(path)
+      && typeof candidate === 'string'
+      && containingSecrets.some((secret) => candidate === secret);
+    if (credentialField && !allowedPaths.has(path)) violations.push(path);
+    if (containingSecrets.length > 0 && !exactAllowedIssuanceValue) violations.push(path);
+  });
+  if (violations.length > 0) throw new UnsafeCredentialOutputError(violations);
+}
+
+export function projectCliErrorValue(value: unknown, sensitiveInputs: readonly string[]): unknown {
+  const secrets = new Set(sensitiveInputs.filter(Boolean));
+  return project(value, secrets);
+}
+
+export function projectCliErrorMessage(message: string, sensitiveInputs: readonly string[]): string {
+  return sensitiveInputs
+    .filter(Boolean)
+    .sort((left, right) => right.length - left.length)
+    .reduce((projected, secret) => projected.replaceAll(secret, '[REDACTED_CREDENTIAL]'), message);
+}
+
+function project(value: unknown, secrets: ReadonlySet<string>): unknown {
+  if (typeof value === 'string') {
+    return [...secrets]
+      .sort((left, right) => right.length - left.length)
+      .reduce((projected, secret) => projected.replaceAll(secret, '[REDACTED_CREDENTIAL]'), value);
+  }
+  if (Array.isArray(value)) return value.map((entry) => project(entry, secrets));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => !CREDENTIAL_FIELD_NAMES.has(key))
+      .map(([key, candidate]) => [key, project(candidate, secrets)]),
+  );
+}
+
+function visit(
+  value: unknown,
+  path: string,
+  visitor: (path: string, key: string | null, value: unknown) => void,
+  key: string | null = null,
+): void {
+  visitor(path, key, value);
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => visit(entry, `${path}[${index}]`, visitor));
+    return;
+  }
+  if (!isRecord(value)) return;
+  for (const [childKey, child] of Object.entries(value)) {
+    visit(child, `${path}.${childKey}`, visitor, childKey);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/credential-transport.ts

@@ -0,0 +1,215 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  readFileSync,
+  unlinkSync,
+} from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from './errors.js';
+import { ensureDirectory, writeJsonAtomic } from './fs-utils.js';
+
+export type CredentialKind = 'writer-lease' | 'claim-token';
+
+interface StoredCredentialReference {
+  schemaVersion: 1;
+  referenceId: string;
+  kind: CredentialKind;
+  projectId: string;
+  entityId: string;
+  actor: string;
+  allowedActions: string[];
+  token: string;
+  tokenSha256: string;
+  createdAt: string;
+  expiresAt: string;
+  oneTime: boolean;
+}
+
+export interface PublicCredentialReference {
+  credentialRef: string;
+  kind: CredentialKind;
+  entityId: string;
+  actor: string;
+  allowedActions: string[];
+  expiresAt: string;
+  transport: 'local-vault-v1';
+  oneTime: boolean;
+}
+
+const REFERENCE_PATTERN = /^CREF-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/;
+
+export function issueCredentialReference(input: {
+  stateRoot: string;
+  projectId: string;
+  entityId: string;
+  actor: string;
+  kind: CredentialKind;
+  token: string;
+  allowedActions: readonly string[];
+  expiresAt: string;
+  oneTime: boolean;
+  now?: Date;
+}): PublicCredentialReference {
+  const token = input.token.trim();
+  if (!token) throw new WorkflowError('STATE_CORRUPT', 'Cannot issue an empty credential reference.');
+  const referenceId = `CREF-${randomUUID()}`;
+  const actor = input.actor.trim();
+  const allowedActions = [...new Set(input.allowedActions.map((value) => value.trim()).filter(Boolean))].sort();
+  if (!actor || allowedActions.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Credential reference requires an actor and at least one action.');
+  }
+  const record: StoredCredentialReference = {
+    schemaVersion: 1,
+    referenceId,
+    kind: input.kind,
+    projectId: input.projectId,
+    entityId: input.entityId,
+    actor,
+    allowedActions,
+    token,
+    tokenSha256: createHash('sha256').update(token).digest('hex'),
+    createdAt: (input.now ?? new Date()).toISOString(),
+    expiresAt: new Date(input.expiresAt).toISOString(),
+    oneTime: input.oneTime,
+  };
+  const file = credentialFile(input.stateRoot, input.projectId, referenceId);
+  writeJsonAtomic(file, record);
+  chmodSync(file, 0o600);
+  return publicReference(record);
+}
+
+export function resolveCredentialReference(input: {
+  stateRoot: string;
+  projectId: string;
+  reference: string;
+  kind: CredentialKind;
+  entityId: string;
+  actor?: string | null;
+  action: string;
+  now?: Date;
+}): { token: string; reference: PublicCredentialReference } {
+  const file = credentialFile(input.stateRoot, input.projectId, input.reference);
+  if (!existsSync(file)) {
+    throw new WorkflowError('NOT_FOUND', 'Local credential reference is missing or already consumed.', {
+      credentialRef: input.reference,
+    });
+  }
+  const metadata = lstatSync(file);
+  if (metadata.isSymbolicLink() || !metadata.isFile() || (metadata.mode & 0o077) !== 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Local credential reference must be a private regular file.', {
+      credentialRef: input.reference,
+    });
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(file, 'utf8')) as unknown;
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', 'Local credential reference is not valid JSON.', {
+      credentialRef: input.reference,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  const record = validateRecord(value, input.reference);
+  const actor = input.actor?.trim() || record.actor;
+  const now = (input.now ?? new Date()).getTime();
+  if (
+    record.projectId !== input.projectId
+    || record.kind !== input.kind
+    || record.entityId !== input.entityId
+    || record.actor !== actor
+    || !record.allowedActions.includes(input.action)
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Local credential reference is not bound to this transition.', {
+      credentialRef: input.reference,
+      expected: { kind: input.kind, entityId: input.entityId, actor, action: input.action },
+      actual: {
+        kind: record.kind,
+        entityId: record.entityId,
+        actor: record.actor,
+        allowedActions: record.allowedActions,
+      },
+    });
+  }
+  if (Date.parse(record.expiresAt) <= now) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Local credential reference has expired.', {
+      credentialRef: input.reference,
+      expiresAt: record.expiresAt,
+    });
+  }
+  if (createHash('sha256').update(record.token).digest('hex') !== record.tokenSha256) {
+    throw new WorkflowError('STATE_CORRUPT', 'Local credential reference failed its integrity check.', {
+      credentialRef: input.reference,
+    });
+  }
+  return { token: record.token, reference: publicReference(record) };
+}
+
+export function consumeCredentialReference(stateRoot: string, projectId: string, reference: string): void {
+  const file = credentialFile(stateRoot, projectId, reference);
+  if (!existsSync(file)) return;
+  const metadata = lstatSync(file);
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Refusing to consume a non-regular credential reference.', {
+      credentialRef: reference,
+    });
+  }
+  unlinkSync(file);
+}
+
+export function assertNoLegacyCredentialArguments(optionNames: ReadonlySet<string>): void {
+  const legacy = ['writer-token', 'claim-token'].filter((name) => optionNames.has(name));
+  if (legacy.length === 0) return;
+  throw new WorkflowError(
+    'INVALID_ARGUMENT',
+    'Secret-bearing CLI options are disabled. Use --writer-credential-ref or --claim-credential-ref.',
+    { rejectedOptions: legacy.map((name) => `--${name}`), credentialTransport: 'local-vault-v1' },
+  );
+}
+
+function credentialFile(stateRoot: string, projectId: string, reference: string): string {
+  const match = REFERENCE_PATTERN.exec(reference);
+  if (!match) throw new WorkflowError('INVALID_ARGUMENT', 'Credential reference has an invalid format.');
+  if (!/^[a-f0-9]{24}$/.test(projectId)) throw new WorkflowError('STATE_CORRUPT', 'Credential project identity is invalid.');
+  const root = path.join(path.resolve(stateRoot), 'credentials', projectId);
+  ensureDirectory(root);
+  const file = path.join(root, `${reference}.json`);
+  if (path.dirname(file) !== root) throw new WorkflowError('STATE_CORRUPT', 'Credential reference escaped its vault.');
+  return file;
+}
+
+function validateRecord(value: unknown, reference: string): StoredCredentialReference {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Credential reference record is invalid.', { credentialRef: reference });
+  }
+  const record = value as Partial<StoredCredentialReference>;
+  const valid = record.schemaVersion === 1
+    && record.referenceId === reference
+    && (record.kind === 'writer-lease' || record.kind === 'claim-token')
+    && typeof record.projectId === 'string'
+    && typeof record.entityId === 'string'
+    && typeof record.actor === 'string'
+    && Array.isArray(record.allowedActions)
+    && record.allowedActions.every((entry) => typeof entry === 'string')
+    && typeof record.token === 'string'
+    && typeof record.tokenSha256 === 'string'
+    && typeof record.createdAt === 'string'
+    && typeof record.expiresAt === 'string'
+    && typeof record.oneTime === 'boolean';
+  if (!valid) throw new WorkflowError('STATE_CORRUPT', 'Credential reference record has an invalid schema.', { credentialRef: reference });
+  return record as StoredCredentialReference;
+}
+
+function publicReference(record: StoredCredentialReference): PublicCredentialReference {
+  return {
+    credentialRef: record.referenceId,
+    kind: record.kind,
+    entityId: record.entityId,
+    actor: record.actor,
+    allowedActions: [...record.allowedActions],
+    expiresAt: record.expiresAt,
+    transport: 'local-vault-v1',
+    oneTime: record.oneTime,
+  };
+}

package/src/delegation.ts

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import type {
+  DelegatedAuthorizationEvidence,
+  DelegationGrant,
+  DelegationGrantGate,
+  DelegationPolicyInput,
+  DelegationTransition,
+  MilestoneState,
+  ProjectKnowledgeMap,
+  TaskState,
+} from './contracts.js';
+import { WorkflowError } from './errors.js';
+
+const TRANSITIONS: readonly DelegationTransition[] = [
+  'project_memory.approve',
+  'task.execution_authorize',
+  'task.final_accept',
+  'milestone.execution_authorize',
+  'milestone.final_accept',
+];
+
+type DelegationTarget = TaskState | MilestoneState | ProjectKnowledgeMap;
+
+export function prepareDelegationGrantGate(
+  projectId: string,
+  input: DelegationPolicyInput,
+  now: Date,
+): DelegationGrantGate {
+  const policy = normalizeDelegationPolicy(input, now);
+  const policyHash = hashDelegationPolicy(projectId, policy);
+  const binding = ['delegation-grant-issuance-v1', projectId, policyHash].join('\0');
+  return {
+    kind: 'delegation_grant_issuance',
+    projectId,
+    policy,
+    policyHash,
+    confirmationCode: `DGA-${createHash('sha256').update(binding).digest('hex').slice(0, 24).toUpperCase()}`,
+  };
+}
+
+export function normalizeDelegationPolicy(
+  input: DelegationPolicyInput,
+  now: Date,
+): DelegationPolicyInput {
+  const principal = input.principal?.trim();
+  const delegate = input.delegate?.trim();
+  if (!principal || !delegate) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation requires non-empty principal and delegate values.');
+  }
+  if (principal === delegate) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation principal and delegate must be distinct audit actors.');
+  }
+  if (!input.scope || !['project', 'milestone', 'task'].includes(input.scope.kind)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation scope must be project, milestone, or task.');
+  }
+  const scope = normalizeScope(input.scope);
+  if (!Array.isArray(input.transitions) || input.transitions.length === 0) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation requires at least one allowed transition.');
+  }
+  const transitions = [...new Set(input.transitions)];
+  if (transitions.some((transition) => !TRANSITIONS.includes(transition))) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation contains an unsupported transition.', {
+      supportedTransitions: TRANSITIONS,
+    });
+  }
+  transitions.sort();
+  if (transitions.includes('project_memory.approve') && scope.kind !== 'project') {
+    throw new WorkflowError(
+      'INVALID_ARGUMENT',
+      'project_memory.approve requires project scope.',
+    );
+  }
+  const expiresAtDate = new Date(input.expiresAt);
+  if (!Number.isFinite(expiresAtDate.getTime())) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation expiresAt must be a valid ISO-8601 timestamp.');
+  }
+  if (expiresAtDate.getTime() <= now.getTime()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Delegation expiresAt must be in the future.');
+  }
+  return {
+    principal,
+    delegate,
+    scope,
+    transitions,
+    expiresAt: expiresAtDate.toISOString(),
+  };
+}
+
+export function hashDelegationPolicy(projectId: string, policy: DelegationPolicyInput): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      version: 'delegation-policy-v1',
+      projectId,
+      principal: policy.principal,
+      delegate: policy.delegate,
+      scope: policy.scope,
+      transitions: policy.transitions,
+      expiresAt: policy.expiresAt,
+    }))
+    .digest('hex');
+}
+
+export function assertDelegationCanAuthorize(
+  grant: DelegationGrant,
+  transition: DelegationTransition,
+  actor: string,
+  target: DelegationTarget,
+  now: Date,
+): DelegatedAuthorizationEvidence {
+  const expectedPolicyHash = hashDelegationPolicy(grant.projectId, {
+    principal: grant.principal,
+    delegate: grant.delegate,
+    scope: grant.scope,
+    transitions: grant.transitions,
+    expiresAt: grant.expiresAt,
+  });
+  if (grant.policyHash !== expectedPolicyHash) {
+    throw new WorkflowError('STATE_CORRUPT', `Delegation ${grant.id} policy hash is invalid.`, {
+      expectedPolicyHash,
+      actualPolicyHash: grant.policyHash,
+    });
+  }
+  const expiry = new Date(grant.expiresAt).getTime();
+  if (!Number.isFinite(expiry)) {
+    throw new WorkflowError('STATE_CORRUPT', `Delegation ${grant.id} has an invalid expiresAt value.`);
+  }
+  if (grant.status !== 'active') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grant.id} is ${grant.status}.`);
+  }
+  if (expiry <= now.getTime()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grant.id} has expired.`, {
+      expiresAt: grant.expiresAt,
+    });
+  }
+  const normalizedActor = actor.trim();
+  if (!normalizedActor || normalizedActor !== grant.delegate) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grant.id} does not authorize actor ${normalizedActor || '<empty>'}.`, {
+      expectedDelegate: grant.delegate,
+    });
+  }
+  if (!grant.transitions.includes(transition)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grant.id} does not allow ${transition}.`);
+  }
+  if (!delegationScopeMatches(grant, target)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grant.id} does not cover ${target.id}.`, {
+      scope: grant.scope,
+    });
+  }
+  return {
+    grantId: grant.id,
+    policyHash: grant.policyHash,
+    principal: grant.principal,
+    delegate: grant.delegate,
+    transition,
+  };
+}
+
+export function delegationCanAuthorize(
+  grant: DelegationGrant,
+  transition: DelegationTransition,
+  target: DelegationTarget,
+  now: Date,
+): boolean {
+  const expiry = new Date(grant.expiresAt).getTime();
+  return grant.status === 'active'
+    && Number.isFinite(expiry)
+    && expiry > now.getTime()
+    && grant.transitions.includes(transition)
+    && delegationScopeMatches(grant, target);
+}
+
+function delegationScopeMatches(grant: DelegationGrant, target: DelegationTarget): boolean {
+  if (grant.scope.kind === 'project') return true;
+  if (target.kind === 'knowledge-map') return false;
+  if (grant.scope.kind === 'task') return target.kind === 'task' && grant.scope.id === target.id;
+  if (target.kind === 'milestone') return grant.scope.id === target.id;
+  return target.milestoneId === grant.scope.id;
+}
+
+function normalizeScope(scope: DelegationPolicyInput['scope']): DelegationPolicyInput['scope'] {
+  if (scope.kind === 'project') return { kind: 'project' };
+  const id = scope.id?.trim();
+  const pattern = scope.kind === 'milestone'
+    ? /^MS-[0-9A-HJKMNP-TV-Z]{26}$/
+    : /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/;
+  if (!id || !pattern.test(id)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Delegation ${scope.kind} scope requires a valid entity ID.`);
+  }
+  return { kind: scope.kind, id };
+}