@etiquekit/etq 1.0.14 → 1.0.16

package/packages/control/src/authority/lease.ts

@@ -1,261 +0,0 @@
-type JsonRecord = Record<string, unknown>;
-
-export const AUTHORITY_LEASE_SCHEMA = 'authority_lease.v0';
-export const AUTHORITY_LEASE_ACTION_VALIDATION_SCHEMA = 'authority-lease-action-validation.v0';
-
-export interface AuthorityLeasePrincipal {
-  principal: string;
-  authority_source: 'human_gate' | 'policy_gate' | 'human_or_policy_gate';
-}
-
-export interface AuthorityLeaseSubject {
-  seat_id: string;
-  operator_principal?: string;
-}
-
-export interface AuthorityLeaseScope {
-  repo_ref?: string;
-  workflow?: string;
-  task_classes: string[];
-}
-
-export interface AuthorityLeaseValidationEnvelope {
-  required: string[];
-}
-
-export interface AuthorityLeaseAuthorityFlags {
-  can_mint_authority: false;
-  can_extend_own_lease: false;
-  can_subdelegate: false;
-  can_auto_merge_in_v0: false;
-}
-
-export interface AuthorityLease {
-  schema: typeof AUTHORITY_LEASE_SCHEMA;
-  lease_id: string;
-  issued_at: string;
-  expires_at: string;
-  issued_by: AuthorityLeasePrincipal;
-  issued_to: AuthorityLeaseSubject;
-  scope: AuthorityLeaseScope;
-  allowed_tools: string[];
-  gated_tools: string[];
-  forbidden_tools: string[];
-  validation_envelope: AuthorityLeaseValidationEnvelope;
-  revocation: {
-    canonical_revocation_ref: string | null;
-  };
-  authority_flags: AuthorityLeaseAuthorityFlags;
-}
-
-export interface AuthorityLeaseCanonicalState {
-  at: string;
-  revoked_lease_ids?: string[];
-}
-
-export interface AuthorityLeaseValidationInput {
-  capability: string;
-  validation_results: Record<string, boolean>;
-  canonical_state: AuthorityLeaseCanonicalState;
-  evidence_ref?: string;
-}
-
-export interface AuthorityLeaseActionValidation {
-  schema: typeof AUTHORITY_LEASE_ACTION_VALIDATION_SCHEMA;
-  lease_ref: string;
-  capability_used: string;
-  verdict: 'legitimate' | 'blocked';
-  reasons: string[];
-  validation: {
-    required: string[];
-    passed: string[];
-    missing_or_failed: string[];
-  };
-  evidence_ref: string | null;
-  authority_boundary: AuthorityLeaseAuthorityFlags & {
-    minted_authority: false;
-    point_of_effect_checked: true;
-    telemetry_is_audit_log: false;
-  };
-}
-
-function isRecord(value: unknown): value is JsonRecord {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function asRecord(value: unknown, field: string): JsonRecord {
-  if (!isRecord(value)) throw new Error(`${field} must be an object`);
-  return value;
-}
-
-function asString(record: JsonRecord, field: string): string {
-  const value = record[field];
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${field} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function optionalString(record: JsonRecord, field: string): string | undefined {
-  const value = record[field];
-  if (value === undefined) return undefined;
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${field} must be a non-empty string when present`);
-  }
-  return value.trim();
-}
-
-function asStringArray(record: JsonRecord, field: string): string[] {
-  const value = record[field];
-  if (!Array.isArray(value) || value.length === 0) throw new Error(`${field} must be a non-empty string array`);
-  return value.map((item) => {
-    if (typeof item !== 'string' || item.trim().length === 0) {
-      throw new Error(`${field} must contain only non-empty strings`);
-    }
-    return item.trim();
-  });
-}
-
-function asFalse(record: JsonRecord, field: keyof AuthorityLeaseAuthorityFlags): false {
-  if (record[field] !== false) throw new Error(`authority_flags.${field} must be false`);
-  return false;
-}
-
-function assertIso(value: string, field: string): string {
-  const date = new Date(value);
-  if (!Number.isFinite(date.getTime())) throw new Error(`${field} must be an ISO-8601 timestamp`);
-  return date.toISOString();
-}
-
-function assertPortableRef(value: string, field: string): void {
-  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
-    throw new Error(`${field} must be an opaque or repo-relative ref, not a local absolute path`);
-  }
-  if (/[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
-    throw new Error(`${field} must be an opaque or repo-relative ref, not a URL`);
-  }
-}
-
-function assertNonOverlapping(left: string[], right: string[], leftName: string, rightName: string): void {
-  const overlap = left.filter((item) => right.includes(item));
-  if (overlap.length > 0) throw new Error(`${leftName} and ${rightName} overlap: ${overlap.join(', ')}`);
-}
-
-function parsePrincipal(value: unknown, field: string): AuthorityLeasePrincipal {
-  const record = asRecord(value, field);
-  const source = asString(record, 'authority_source');
-  if (!['human_gate', 'policy_gate', 'human_or_policy_gate'].includes(source)) {
-    throw new Error('authority_source must be one of: human_gate, policy_gate, human_or_policy_gate');
-  }
-  return {
-    principal: asString(record, 'principal'),
-    authority_source: source as AuthorityLeasePrincipal['authority_source'],
-  };
-}
-
-function parseSubject(value: unknown): AuthorityLeaseSubject {
-  const record = asRecord(value, 'issued_to');
-  return {
-    seat_id: asString(record, 'seat_id'),
-    operator_principal: optionalString(record, 'operator_principal'),
-  };
-}
-
-function parseScope(value: unknown): AuthorityLeaseScope {
-  const record = asRecord(value, 'scope');
-  const repoRef = optionalString(record, 'repo_ref');
-  if (repoRef) assertPortableRef(repoRef, 'scope.repo_ref');
-  return {
-    repo_ref: repoRef,
-    workflow: optionalString(record, 'workflow'),
-    task_classes: asStringArray(record, 'task_classes'),
-  };
-}
-
-function parseAuthorityFlags(value: unknown): AuthorityLeaseAuthorityFlags {
-  const record = asRecord(value, 'authority_flags');
-  return {
-    can_mint_authority: asFalse(record, 'can_mint_authority'),
-    can_extend_own_lease: asFalse(record, 'can_extend_own_lease'),
-    can_subdelegate: asFalse(record, 'can_subdelegate'),
-    can_auto_merge_in_v0: asFalse(record, 'can_auto_merge_in_v0'),
-  };
-}
-
-export function parseAuthorityLease(value: unknown): AuthorityLease {
-  const record = asRecord(value, 'authority lease');
-  if (record.schema !== AUTHORITY_LEASE_SCHEMA) throw new Error(`schema must be ${AUTHORITY_LEASE_SCHEMA}`);
-  const issuedAt = assertIso(asString(record, 'issued_at'), 'issued_at');
-  const expiresAt = assertIso(asString(record, 'expires_at'), 'expires_at');
-  if (Date.parse(expiresAt) <= Date.parse(issuedAt)) throw new Error('expires_at must be after issued_at');
-  const allowedTools = asStringArray(record, 'allowed_tools');
-  const gatedTools = asStringArray(record, 'gated_tools');
-  const forbiddenTools = asStringArray(record, 'forbidden_tools');
-  assertNonOverlapping(allowedTools, forbiddenTools, 'allowed_tools', 'forbidden_tools');
-  assertNonOverlapping(gatedTools, forbiddenTools, 'gated_tools', 'forbidden_tools');
-  const validation = asRecord(record.validation_envelope, 'validation_envelope');
-  const revocation = asRecord(record.revocation, 'revocation');
-  const canonicalRevocationRef = revocation.canonical_revocation_ref;
-  if (canonicalRevocationRef !== null && typeof canonicalRevocationRef !== 'string') {
-    throw new Error('revocation.canonical_revocation_ref must be a string or null');
-  }
-  if (typeof canonicalRevocationRef === 'string') assertPortableRef(canonicalRevocationRef, 'revocation.canonical_revocation_ref');
-  return {
-    schema: AUTHORITY_LEASE_SCHEMA,
-    lease_id: asString(record, 'lease_id'),
-    issued_at: issuedAt,
-    expires_at: expiresAt,
-    issued_by: parsePrincipal(record.issued_by, 'issued_by'),
-    issued_to: parseSubject(record.issued_to),
-    scope: parseScope(record.scope),
-    allowed_tools: allowedTools,
-    gated_tools: gatedTools,
-    forbidden_tools: forbiddenTools,
-    validation_envelope: {
-      required: asStringArray(validation, 'required'),
-    },
-    revocation: {
-      canonical_revocation_ref: canonicalRevocationRef,
-    },
-    authority_flags: parseAuthorityFlags(record.authority_flags),
-  };
-}
-
-export function evaluateAuthorityLeaseAction(
-  rawLease: unknown,
-  input: AuthorityLeaseValidationInput,
-): AuthorityLeaseActionValidation {
-  const lease = parseAuthorityLease(rawLease);
-  const reasons: string[] = [];
-  const pointInTime = Date.parse(assertIso(input.canonical_state.at, 'canonical_state.at'));
-  if (pointInTime > Date.parse(lease.expires_at)) reasons.push('lease_expired');
-  if (lease.revocation.canonical_revocation_ref) reasons.push('lease_revoked');
-  if ((input.canonical_state.revoked_lease_ids ?? []).includes(lease.lease_id)) {
-    reasons.push('lease_revoked_at_point_of_effect');
-  }
-  if (lease.forbidden_tools.includes(input.capability)) reasons.push('capability_forbidden');
-  if (lease.gated_tools.includes(input.capability)) reasons.push('capability_requires_external_gate');
-  if (!lease.allowed_tools.includes(input.capability)) reasons.push('capability_not_allowed');
-  const missingOrFailed = lease.validation_envelope.required.filter((item) => input.validation_results[item] !== true);
-  if (missingOrFailed.length > 0) reasons.push('validation_envelope_failed');
-  const passed = lease.validation_envelope.required.filter((item) => input.validation_results[item] === true);
-  return {
-    schema: AUTHORITY_LEASE_ACTION_VALIDATION_SCHEMA,
-    lease_ref: lease.lease_id,
-    capability_used: input.capability,
-    verdict: reasons.length === 0 ? 'legitimate' : 'blocked',
-    reasons,
-    validation: {
-      required: lease.validation_envelope.required,
-      passed,
-      missing_or_failed: missingOrFailed,
-    },
-    evidence_ref: input.evidence_ref ?? null,
-    authority_boundary: {
-      ...lease.authority_flags,
-      minted_authority: false,
-      point_of_effect_checked: true,
-      telemetry_is_audit_log: false,
-    },
-  };
-}

package/packages/control/src/authority/node-delegation.ts

@@ -1,257 +0,0 @@
-type JsonRecord = Record<string, unknown>;
-
-export const NODE_DELEGATION_SCHEMA = 'node_delegation.v0';
-export const NODE_DELEGATION_VALIDATION_SCHEMA = 'node-delegation-validation.v0';
-
-const AUTHORITY_SCOPES = ['none', 'read_only', 'bounded_write', 'promotion'] as const;
-const LEASE_SCOPES = ['none', 'mechanical_validation', 'read_only_review', 'bounded_write', 'bounded_impl'] as const;
-
-export type NodeDelegationAuthorityScope = (typeof AUTHORITY_SCOPES)[number];
-export type NodeDelegationLeaseScope = (typeof LEASE_SCOPES)[number];
-
-export interface NodeDelegationBoundary {
-  parenthood_grants_authority: false;
-  child_mints_authority: false;
-  child_can_widen_scope: false;
-  child_can_write_parent_ledger: false;
-  validation_is_authorization: false;
-}
-
-export interface NodeDelegationLease {
-  schema: typeof NODE_DELEGATION_SCHEMA;
-  delegation_id: string;
-  issued_at: string;
-  expires_at: string;
-  workflow_id: string;
-  lane: string;
-  parent_node: string;
-  child_node: string;
-  return_to: string;
-  lease_scope: NodeDelegationLeaseScope;
-  authority_scope: NodeDelegationAuthorityScope;
-  allowed_writes: string[];
-  allowed_tools: string[];
-  forbidden_actions: string[];
-  may_spawn_children: boolean;
-  child_spawn_budget: number;
-  max_depth: number;
-  requires_preflight: true;
-  preflight_required: string[];
-  authority_boundary: NodeDelegationBoundary;
-}
-
-export interface NodeDelegationValidation {
-  schema: typeof NODE_DELEGATION_VALIDATION_SCHEMA;
-  parent_ref: string;
-  child_ref: string;
-  verdict: 'legitimate' | 'blocked';
-  reasons: string[];
-  subset_checks: {
-    workflow_matches: boolean;
-    lane_matches: boolean;
-    parent_chain_matches: boolean;
-    child_ttl_within_parent: boolean;
-    lease_scope_subset: boolean;
-    authority_scope_subset: boolean;
-    allowed_writes_subset: boolean;
-    allowed_tools_subset: boolean;
-    forbidden_actions_inherited: boolean;
-    child_spawn_budget_subset: boolean;
-    child_depth_reduced: boolean;
-    preflight_required: boolean;
-  };
-  authority_boundary: NodeDelegationBoundary & {
-    validation_checked_subset: true;
-    validation_grants_authority: false;
-  };
-}
-
-function isRecord(value: unknown): value is JsonRecord {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function asRecord(value: unknown, field: string): JsonRecord {
-  if (!isRecord(value)) throw new Error(`${field} must be an object`);
-  return value;
-}
-
-function asString(record: JsonRecord, field: string): string {
-  const value = record[field];
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${field} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function asStringArray(record: JsonRecord, field: string): string[] {
-  const value = record[field];
-  if (!Array.isArray(value)) throw new Error(`${field} must be a string array`);
-  return value.map((item) => {
-    if (typeof item !== 'string' || item.trim().length === 0) {
-      throw new Error(`${field} must contain only non-empty strings`);
-    }
-    return item.trim();
-  });
-}
-
-function asBoolean(record: JsonRecord, field: string): boolean {
-  const value = record[field];
-  if (typeof value !== 'boolean') throw new Error(`${field} must be boolean`);
-  return value;
-}
-
-function asTrue(record: JsonRecord, field: string): true {
-  if (record[field] !== true) throw new Error(`${field} must be true`);
-  return true;
-}
-
-function asFalse(record: JsonRecord, field: keyof NodeDelegationBoundary): false {
-  if (record[field] !== false) throw new Error(`authority_boundary.${field} must be false`);
-  return false;
-}
-
-function asNonNegativeInteger(record: JsonRecord, field: string): number {
-  const value = record[field];
-  if (!Number.isInteger(value) || Number(value) < 0) throw new Error(`${field} must be a non-negative integer`);
-  return Number(value);
-}
-
-function assertIso(value: string, field: string): string {
-  const date = new Date(value);
-  if (!Number.isFinite(date.getTime())) throw new Error(`${field} must be an ISO-8601 timestamp`);
-  return date.toISOString();
-}
-
-function assertPortableRef(value: string, field: string): void {
-  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
-    throw new Error(`${field} must be an opaque or repo-relative ref, not a local absolute path`);
-  }
-  if (/[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
-    throw new Error(`${field} must be an opaque or repo-relative ref, not a URL`);
-  }
-}
-
-function asEnum<T extends readonly string[]>(values: T, value: unknown, field: string): T[number] {
-  if (typeof value !== 'string' || !values.includes(value)) {
-    throw new Error(`${field} must be one of: ${values.join(', ')}`);
-  }
-  return value as T[number];
-}
-
-function parseBoundary(value: unknown): NodeDelegationBoundary {
-  const record = asRecord(value, 'authority_boundary');
-  return {
-    parenthood_grants_authority: asFalse(record, 'parenthood_grants_authority'),
-    child_mints_authority: asFalse(record, 'child_mints_authority'),
-    child_can_widen_scope: asFalse(record, 'child_can_widen_scope'),
-    child_can_write_parent_ledger: asFalse(record, 'child_can_write_parent_ledger'),
-    validation_is_authorization: asFalse(record, 'validation_is_authorization'),
-  };
-}
-
-export function parseNodeDelegationLease(value: unknown): NodeDelegationLease {
-  const record = asRecord(value, 'node delegation lease');
-  if (record.schema !== NODE_DELEGATION_SCHEMA) throw new Error(`schema must be ${NODE_DELEGATION_SCHEMA}`);
-  const issuedAt = assertIso(asString(record, 'issued_at'), 'issued_at');
-  const expiresAt = assertIso(asString(record, 'expires_at'), 'expires_at');
-  if (Date.parse(expiresAt) <= Date.parse(issuedAt)) throw new Error('expires_at must be after issued_at');
-  const delegationId = asString(record, 'delegation_id');
-  const lane = asString(record, 'lane');
-  const returnTo = asString(record, 'return_to');
-  assertPortableRef(delegationId, 'delegation_id');
-  assertPortableRef(lane, 'lane');
-  assertPortableRef(returnTo, 'return_to');
-  const allowedWrites = asStringArray(record, 'allowed_writes');
-  for (const ref of allowedWrites) assertPortableRef(ref, 'allowed_writes');
-  return {
-    schema: NODE_DELEGATION_SCHEMA,
-    delegation_id: delegationId,
-    issued_at: issuedAt,
-    expires_at: expiresAt,
-    workflow_id: asString(record, 'workflow_id'),
-    lane,
-    parent_node: asString(record, 'parent_node'),
-    child_node: asString(record, 'child_node'),
-    return_to: returnTo,
-    lease_scope: asEnum(LEASE_SCOPES, record.lease_scope, 'lease_scope') as NodeDelegationLeaseScope,
-    authority_scope: asEnum(AUTHORITY_SCOPES, record.authority_scope, 'authority_scope') as NodeDelegationAuthorityScope,
-    allowed_writes: allowedWrites,
-    allowed_tools: asStringArray(record, 'allowed_tools'),
-    forbidden_actions: asStringArray(record, 'forbidden_actions'),
-    may_spawn_children: asBoolean(record, 'may_spawn_children'),
-    child_spawn_budget: asNonNegativeInteger(record, 'child_spawn_budget'),
-    max_depth: asNonNegativeInteger(record, 'max_depth'),
-    requires_preflight: asTrue(record, 'requires_preflight'),
-    preflight_required: asStringArray(record, 'preflight_required'),
-    authority_boundary: parseBoundary(record.authority_boundary),
-  };
-}
-
-function rankAuthority(scope: NodeDelegationAuthorityScope): number {
-  return AUTHORITY_SCOPES.indexOf(scope);
-}
-
-function rankLease(scope: NodeDelegationLeaseScope): number {
-  if (scope === 'none') return 0;
-  if (scope === 'mechanical_validation' || scope === 'read_only_review') return 1;
-  if (scope === 'bounded_write') return 2;
-  return 3;
-}
-
-function isSubset(child: string[], parent: string[]): boolean {
-  return child.every((item) => parent.includes(item));
-}
-
-function includesMinimumPreflight(items: string[]): boolean {
-  return ['workflow_binding', 'current_ledger_head', 'lease_envelope'].every((required) => items.includes(required));
-}
-
-function pushReason(reasons: string[], ok: boolean, reason: string): void {
-  if (!ok) reasons.push(reason);
-}
-
-export function evaluateNodeSubdelegation(parentRaw: unknown, childRaw: unknown): NodeDelegationValidation {
-  const parent = parseNodeDelegationLease(parentRaw);
-  const child = parseNodeDelegationLease(childRaw);
-  const checks = {
-    workflow_matches: child.workflow_id === parent.workflow_id,
-    lane_matches: child.lane === parent.lane,
-    parent_chain_matches: child.parent_node === parent.child_node && child.return_to === parent.child_node,
-    child_ttl_within_parent: Date.parse(child.expires_at) <= Date.parse(parent.expires_at),
-    lease_scope_subset: rankLease(child.lease_scope) <= rankLease(parent.lease_scope),
-    authority_scope_subset: rankAuthority(child.authority_scope) <= rankAuthority(parent.authority_scope),
-    allowed_writes_subset: isSubset(child.allowed_writes, parent.allowed_writes),
-    allowed_tools_subset: isSubset(child.allowed_tools, parent.allowed_tools),
-    forbidden_actions_inherited: isSubset(parent.forbidden_actions, child.forbidden_actions),
-    child_spawn_budget_subset: parent.may_spawn_children && parent.child_spawn_budget > 0 && child.child_spawn_budget <= parent.child_spawn_budget,
-    child_depth_reduced: parent.may_spawn_children && parent.max_depth > 0 && child.max_depth < parent.max_depth,
-    preflight_required: child.requires_preflight && includesMinimumPreflight(child.preflight_required),
-  };
-  const reasons: string[] = [];
-  pushReason(reasons, parent.may_spawn_children, 'parent_forbids_children');
-  pushReason(reasons, checks.workflow_matches, 'workflow_mismatch');
-  pushReason(reasons, checks.lane_matches, 'lane_mismatch');
-  pushReason(reasons, checks.parent_chain_matches, 'parent_chain_mismatch');
-  pushReason(reasons, checks.child_ttl_within_parent, 'child_ttl_exceeds_parent');
-  pushReason(reasons, checks.lease_scope_subset, 'lease_scope_widened');
-  pushReason(reasons, checks.authority_scope_subset, 'authority_scope_widened');
-  pushReason(reasons, checks.allowed_writes_subset, 'allowed_writes_widened');
-  pushReason(reasons, checks.allowed_tools_subset, 'allowed_tools_widened');
-  pushReason(reasons, checks.forbidden_actions_inherited, 'forbidden_actions_not_inherited');
-  pushReason(reasons, checks.child_spawn_budget_subset, 'child_spawn_budget_exceeds_parent');
-  pushReason(reasons, checks.child_depth_reduced, 'child_depth_not_reduced');
-  pushReason(reasons, checks.preflight_required, 'preflight_missing_minimums');
-  return {
-    schema: NODE_DELEGATION_VALIDATION_SCHEMA,
-    parent_ref: parent.delegation_id,
-    child_ref: child.delegation_id,
-    verdict: reasons.length === 0 ? 'legitimate' : 'blocked',
-    reasons,
-    subset_checks: checks,
-    authority_boundary: {
-      ...child.authority_boundary,
-      validation_checked_subset: true,
-      validation_grants_authority: false,
-    },
-  };
-}