@etiquekit/etq 1.0.14 → 1.0.16

package/packages/control/src/sync/join-plan.ts

@@ -1,375 +0,0 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { parse as parseYaml } from 'yaml';
-import { assertSharedMemoryScopeId, detectMemoryRiskFlags } from '../memory/sanitize';
-
-export interface SyncJoinPlanOptions {
-  invitePath: string;
-  joinedBy: string;
-  claimRef: string;
-  at?: string;
-}
-
-export interface SyncJoinPlan {
-  schema: 'sync-join-plan.v0';
-  plan_id: string;
-  created_at: string;
-  joined_by: string;
-  identity_claim_ref: string;
-  invite: {
-    invite_id: string;
-    org_id: string;
-    workspace_id: string;
-    expires_at: string;
-    credential_ref: string;
-    credential: {
-      single_use: true;
-      scoped: true;
-      revocable: true;
-    };
-  };
-  installer: {
-    artifact_ref: string;
-    checksum_ref: string;
-    signature_ref: string;
-    curl_pipe_allowed: false;
-    reviewable_download_required: true;
-  };
-  git_sync: {
-    substrate: 'git';
-    remote_ref: string;
-    default_branch: string;
-    protected_branch: string;
-    invite_maps_to: 'git_clone';
-    downstream_sync_maps_to: 'git_fetch';
-    upstream_maps_to: 'protected_branch_pr';
-    drain_maps_to: 'single_writer_drain';
-    auto_fetch: true;
-    auto_merge: false;
-    merge_control: 'developer_controlled';
-    pull_request_required: true;
-    drain_required: true;
-    event_log_merge_driver_required: true;
-    webhook_is_nudge_only: true;
-    bespoke_sync_engine: false;
-  };
-  receipt_policy: {
-    receipt_reverify_required: true;
-    local_receipt_is_claim_only: true;
-    ci_rubrics_required: true;
-    protected_branch_required: true;
-  };
-  authorization_policy: {
-    joiner_verified: true;
-    workspace_admission_required: true;
-    action_authorization_required: true;
-    grant_required_for_mutation: true;
-  };
-  content_boundary: {
-    raw_invite_secret_included: false;
-    raw_provider_token_included: false;
-    raw_git_remote_url_included: false;
-    local_paths_included: false;
-    install_pipe_included: false;
-  };
-  authority_boundary: {
-    can_authorize_work: false;
-    can_execute_work: false;
-    can_grant: false;
-    can_close_work: false;
-    can_merge: false;
-    hosted_plane_is_source_of_truth: false;
-    sync_plan_is_source_of_truth: false;
-  };
-  next_steps: string[];
-}
-
-type UnknownObject = Record<string, unknown>;
-
-const MAX_INVITE_TTL_MS = 24 * 60 * 60 * 1000;
-const URL_RE = /\b[a-z][a-z0-9+.-]*:\/\//i;
-const HOSTLIKE_RE = /\b[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+\.[a-z]{2,}\b/i;
-const LOCAL_PATH_RE = /(?:^|[\s:])(?:\/Users\/|\/home\/|\/private\/|\/tmp\/|~\/|\$HOME|[A-Za-z]:[\\/])/;
-const RAW_SECRET_RE = /(?:sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|(?:^|[\s:=])(?:token|secret|password|api[_-]?key)\s*[:=])/i;
-
-function isoNow(at?: string): string {
-  const value = at ?? new Date().toISOString();
-  if (!Number.isFinite(Date.parse(value))) {
-    throw new Error('--at must be an ISO-8601 timestamp');
-  }
-  return new Date(value).toISOString();
-}
-
-function stableHash(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
-}
-
-function parseObject(raw: string, path: string): UnknownObject {
-  const parsed = parseYaml(raw);
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${path} must parse as an object`);
-  }
-  return parsed as UnknownObject;
-}
-
-function objectField(parent: UnknownObject, key: string): UnknownObject {
-  const value = parent[key];
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${key} must be an object`);
-  }
-  return value as UnknownObject;
-}
-
-function stringField(parent: UnknownObject, key: string, field = key): string {
-  const value = parent[key];
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${field} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function requireBoolean(parent: UnknownObject, key: string, expected: boolean): void {
-  if (parent[key] !== expected) {
-    throw new Error(`${key} must be ${String(expected)}`);
-  }
-}
-
-function assertSafeRef(value: string, field: string, options: { allowHost?: boolean } = {}): string {
-  const trimmed = value.trim();
-  if (!trimmed || trimmed.length > 240) {
-    throw new Error(`${field} must be a non-empty ref <= 240 chars`);
-  }
-  if (URL_RE.test(trimmed) || (!options.allowHost && HOSTLIKE_RE.test(trimmed))) {
-    throw new Error(`${field} must be an opaque ref, not a URL or host`);
-  }
-  if (LOCAL_PATH_RE.test(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(trimmed)) {
-    throw new Error(`${field} must not include a local path`);
-  }
-  if (trimmed.includes('..') || trimmed.includes('\\')) {
-    throw new Error(`${field} must not include path traversal`);
-  }
-  if (RAW_SECRET_RE.test(trimmed)) {
-    throw new Error(`${field} must not include a raw secret or token`);
-  }
-  const flags = detectMemoryRiskFlags(trimmed).filter((flag) => flag !== 'contains_hostname');
-  if (flags.length > 0) {
-    throw new Error(`${field} contains restricted shared-sync content: ${flags.join(', ')}`);
-  }
-  if (!/^[A-Za-z0-9][A-Za-z0-9._:@/+,-]{0,239}$/.test(trimmed)) {
-    throw new Error(`${field} must be an opaque ref`);
-  }
-  return trimmed;
-}
-
-function assertOpaqueId(value: string, field: string): string {
-  assertSharedMemoryScopeId(value, field);
-  return value;
-}
-
-function requireIso(value: string, field: string): string {
-  if (!Number.isFinite(Date.parse(value))) {
-    throw new Error(`${field} must be an ISO-8601 timestamp`);
-  }
-  return new Date(value).toISOString();
-}
-
-function assertInviteWindow(createdAt: string, expiresAt: string, now: string): void {
-  const created = Date.parse(createdAt);
-  const expires = Date.parse(expiresAt);
-  const current = Date.parse(now);
-  if (expires <= created) {
-    throw new Error('expires_at must be after created_at');
-  }
-  if (expires - created > MAX_INVITE_TTL_MS) {
-    throw new Error('invite expiry must be short-lived (<= 24h)');
-  }
-  if (current < created) {
-    throw new Error('invite is not valid yet');
-  }
-  if (current >= expires) {
-    throw new Error('invite is expired');
-  }
-}
-
-function requireOneOf<T extends string>(value: string, allowed: readonly T[], field: string): T {
-  if (!(allowed as readonly string[]).includes(value)) {
-    throw new Error(`${field} must be one of: ${allowed.join(', ')}`);
-  }
-  return value as T;
-}
-
-export async function buildSyncJoinPlan(options: SyncJoinPlanOptions): Promise<SyncJoinPlan> {
-  const createdAt = isoNow(options.at);
-  const raw = await readFile(options.invitePath, 'utf-8');
-  const invite = parseObject(raw, options.invitePath);
-  if (stringField(invite, 'schema') !== 'sync-invite.v0') {
-    throw new Error('invite schema must be sync-invite.v0');
-  }
-
-  const inviteId = assertSafeRef(stringField(invite, 'invite_id'), 'invite_id');
-  const orgId = assertOpaqueId(stringField(invite, 'org_id'), 'org_id');
-  const workspaceId = assertOpaqueId(stringField(invite, 'workspace_id'), 'workspace_id');
-  const inviteCreatedAt = requireIso(stringField(invite, 'created_at'), 'created_at');
-  const expiresAt = requireIso(stringField(invite, 'expires_at'), 'expires_at');
-  assertInviteWindow(inviteCreatedAt, expiresAt, createdAt);
-
-  const credential = objectField(invite, 'credential');
-  const credentialRef = assertSafeRef(stringField(credential, 'ref', 'credential.ref'), 'credential.ref');
-  requireBoolean(credential, 'single_use', true);
-  requireBoolean(credential, 'scoped', true);
-  requireBoolean(credential, 'revocable', true);
-
-  const joiner = objectField(invite, 'joiner');
-  requireOneOf(
-    stringField(joiner, 'required_assurance', 'joiner.required_assurance'),
-    ['verified_identity'] as const,
-    'joiner.required_assurance',
-  );
-
-  const installer = objectField(invite, 'installer');
-  const artifactRef = assertSafeRef(stringField(installer, 'artifact_ref', 'installer.artifact_ref'), 'installer.artifact_ref');
-  const checksumRef = assertSafeRef(stringField(installer, 'checksum_ref', 'installer.checksum_ref'), 'installer.checksum_ref');
-  const signatureRef = assertSafeRef(stringField(installer, 'signature_ref', 'installer.signature_ref'), 'installer.signature_ref');
-  requireBoolean(installer, 'curl_pipe_allowed', false);
-  requireBoolean(installer, 'reviewable_download_required', true);
-
-  const git = objectField(invite, 'git');
-  const remoteRef = assertSafeRef(stringField(git, 'remote_ref', 'git.remote_ref'), 'git.remote_ref');
-  const defaultBranch = assertSafeRef(stringField(git, 'default_branch', 'git.default_branch'), 'git.default_branch', { allowHost: true });
-  const protectedBranch = assertSafeRef(stringField(git, 'protected_branch', 'git.protected_branch'), 'git.protected_branch', { allowHost: true });
-  requireBoolean(git, 'pull_request_required', true);
-  requireBoolean(git, 'drain_required', true);
-
-  const syncPolicy = objectField(invite, 'sync_policy');
-  requireBoolean(syncPolicy, 'auto_fetch', true);
-  requireBoolean(syncPolicy, 'auto_merge', false);
-  const mergeControl = requireOneOf(
-    stringField(syncPolicy, 'merge_control'),
-    ['developer_controlled', 'dev_controlled'] as const,
-    'sync_policy.merge_control',
-  );
-  requireBoolean(syncPolicy, 'receipt_reverify_required', true);
-  requireBoolean(syncPolicy, 'ci_rubrics_required', true);
-  if (syncPolicy.hosted_plane_source_of_truth !== undefined) {
-    requireBoolean(syncPolicy, 'hosted_plane_source_of_truth', false);
-  }
-
-  const webhook = invite.webhook === undefined ? undefined : objectField(invite, 'webhook');
-  if (webhook) requireBoolean(webhook, 'nudge_only', true);
-
-  const joinedBy = assertOpaqueId(options.joinedBy, '--joined-by');
-  const claimRef = assertSafeRef(options.claimRef, '--claim-ref');
-  const planBasis = {
-    inviteId,
-    orgId,
-    workspaceId,
-    joinedBy,
-    claimRef,
-    createdAt,
-  };
-
-  return {
-    schema: 'sync-join-plan.v0',
-    plan_id: `sync-join:${stableHash(planBasis)}`,
-    created_at: createdAt,
-    joined_by: joinedBy,
-    identity_claim_ref: claimRef,
-    invite: {
-      invite_id: inviteId,
-      org_id: orgId,
-      workspace_id: workspaceId,
-      expires_at: expiresAt,
-      credential_ref: credentialRef,
-      credential: {
-        single_use: true,
-        scoped: true,
-        revocable: true,
-      },
-    },
-    installer: {
-      artifact_ref: artifactRef,
-      checksum_ref: checksumRef,
-      signature_ref: signatureRef,
-      curl_pipe_allowed: false,
-      reviewable_download_required: true,
-    },
-    git_sync: {
-      substrate: 'git',
-      remote_ref: remoteRef,
-      default_branch: defaultBranch,
-      protected_branch: protectedBranch,
-      invite_maps_to: 'git_clone',
-      downstream_sync_maps_to: 'git_fetch',
-      upstream_maps_to: 'protected_branch_pr',
-      drain_maps_to: 'single_writer_drain',
-      auto_fetch: true,
-      auto_merge: false,
-      merge_control: mergeControl === 'dev_controlled' ? 'developer_controlled' : mergeControl,
-      pull_request_required: true,
-      drain_required: true,
-      event_log_merge_driver_required: true,
-      webhook_is_nudge_only: true,
-      bespoke_sync_engine: false,
-    },
-    receipt_policy: {
-      receipt_reverify_required: true,
-      local_receipt_is_claim_only: true,
-      ci_rubrics_required: true,
-      protected_branch_required: true,
-    },
-    authorization_policy: {
-      joiner_verified: true,
-      workspace_admission_required: true,
-      action_authorization_required: true,
-      grant_required_for_mutation: true,
-    },
-    content_boundary: {
-      raw_invite_secret_included: false,
-      raw_provider_token_included: false,
-      raw_git_remote_url_included: false,
-      local_paths_included: false,
-      install_pipe_included: false,
-    },
-    authority_boundary: {
-      can_authorize_work: false,
-      can_execute_work: false,
-      can_grant: false,
-      can_close_work: false,
-      can_merge: false,
-      hosted_plane_is_source_of_truth: false,
-      sync_plan_is_source_of_truth: false,
-    },
-    next_steps: [
-      'verify installer signature and checksum before installing etiquette',
-      'resolve remote_ref through the organization credential broker, then git clone',
-      'run etiquette sync install-git-merge-driver once inside the clone',
-      'run workspace admission with the joined_by principal and identity_claim_ref',
-      'use git fetch for downstream updates; merges remain developer controlled',
-      'submit work through a protected branch and PR; drain serializes canonical ledger writes',
-      're-run rubrics in CI before accepting any receipt projection',
-    ],
-  };
-}
-
-export function renderSyncJoinPlan(plan: SyncJoinPlan): string {
-  return [
-    'sync_join_plan:',
-    `  plan_id: ${plan.plan_id}`,
-    `  joined_by: ${plan.joined_by}`,
-    `  workspace: ${plan.invite.org_id}/${plan.invite.workspace_id}`,
-    `  invite_expires_at: ${plan.invite.expires_at}`,
-    `  remote_ref: ${plan.git_sync.remote_ref}`,
-    `  installer_signature_required: ${String(Boolean(plan.installer.signature_ref))}`,
-    `  installer_checksum_required: ${String(Boolean(plan.installer.checksum_ref))}`,
-    `  curl_pipe_allowed: ${String(plan.installer.curl_pipe_allowed)}`,
-    `  substrate: ${plan.git_sync.substrate}`,
-    `  auto_fetch: ${String(plan.git_sync.auto_fetch)}`,
-    `  auto_merge: ${String(plan.git_sync.auto_merge)}`,
-    `  pull_request_required: ${String(plan.git_sync.pull_request_required)}`,
-    `  drain_required: ${String(plan.git_sync.drain_required)}`,
-    `  event_log_merge_driver_required: ${String(plan.git_sync.event_log_merge_driver_required)}`,
-    `  receipt_reverify_required: ${String(plan.receipt_policy.receipt_reverify_required)}`,
-    `  bespoke_sync_engine: ${String(plan.git_sync.bespoke_sync_engine)}`,
-    `  hosted_plane_is_source_of_truth: ${String(plan.authority_boundary.hosted_plane_is_source_of_truth)}`,
-  ].join('\n');
-}