@etiquekit/etq 1.0.12 → 1.0.14

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

@@ -0,0 +1,375 @@
+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');
+}