borgmcp-shared 0.7.1 → 0.8.1

package/src/protocol/contract.ts

@@ -13,7 +13,7 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.7.1' as const;
+export const SHARED_PACKAGE_VERSION = '0.8.1' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
@@ -125,6 +125,23 @@ export interface EnrollmentExchangeRequest {
   client_name?: string;
 }
 
+export const INVITATION_ARTIFACT_VERSION = 2 as const;
+export type InvitationAuthority = 'client' | 'owner';
+
+/**
+ * The single opaque value transported between machines for enrollment. The
+ * integrity field is produced and verified by the issuing implementation; the
+ * shared codec preserves it as a bounded canonical field.
+ */
+export interface InvitationArtifact {
+  version: typeof INVITATION_ARTIFACT_VERSION;
+  endpoint: string;
+  ca_spki_sha256: string;
+  authority: InvitationAuthority;
+  secret: string;
+  integrity: string;
+}
+
 export const SERVER_CAPABILITIES = ['create_cube'] as const;
 export type ServerCapability = (typeof SERVER_CAPABILITIES)[number];
 
@@ -315,6 +332,207 @@ function opaqueToken(value: unknown, path: readonly (string | number)[]): string
   return token;
 }
 
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const INVITATION_MAGIC = 'B2';
+const INVITATION_LENGTH_HEX_DIGITS = 3;
+
+function encodeBase64UrlAscii(value: string): string {
+  let output = '';
+  for (let index = 0; index < value.length; index += 3) {
+    const first = value.charCodeAt(index);
+    const hasSecond = index + 1 < value.length;
+    const hasThird = index + 2 < value.length;
+    const second = hasSecond ? value.charCodeAt(index + 1) : 0;
+    const third = hasThird ? value.charCodeAt(index + 2) : 0;
+    output += BASE64URL_ALPHABET[first >> 2];
+    output += BASE64URL_ALPHABET[((first & 0x03) << 4) | (second >> 4)];
+    if (hasSecond) output += BASE64URL_ALPHABET[((second & 0x0f) << 2) | (third >> 6)];
+    if (hasThird) output += BASE64URL_ALPHABET[third & 0x3f];
+  }
+  return output;
+}
+
+function decodeBase64UrlAscii(value: string, path: readonly (string | number)[]): string {
+  if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
+    fail('Expected an unpadded base64url value.', path);
+  }
+  let output = '';
+  for (let index = 0; index < value.length; index += 4) {
+    const first = BASE64URL_ALPHABET.indexOf(value[index]);
+    const second = BASE64URL_ALPHABET.indexOf(value[index + 1]);
+    const third = index + 2 < value.length ? BASE64URL_ALPHABET.indexOf(value[index + 2]) : 0;
+    const fourth = index + 3 < value.length ? BASE64URL_ALPHABET.indexOf(value[index + 3]) : 0;
+    if (first < 0 || second < 0 || (index + 2 < value.length && third < 0) ||
+        (index + 3 < value.length && fourth < 0)) {
+      fail('Expected an unpadded base64url value.', path);
+    }
+    const bytes = [
+      (first << 2) | (second >> 4),
+      ((second & 0x0f) << 4) | (third >> 2),
+      ((third & 0x03) << 6) | fourth,
+    ];
+    const byteCount = Math.min(3, value.length - index - 1);
+    for (let byteIndex = 0; byteIndex < byteCount; byteIndex++) {
+      if (bytes[byteIndex] > 0x7f) fail('Invitation fields must contain ASCII bytes.', path);
+      output += String.fromCharCode(bytes[byteIndex]);
+    }
+  }
+  if (encodeBase64UrlAscii(output) !== value) {
+    fail('Expected canonical unpadded base64url encoding.', path);
+  }
+  return output;
+}
+
+function encodedBase64UrlLength(byteLength: number): number {
+  const remainder = byteLength % 3;
+  return Math.floor(byteLength / 3) * 4 + (remainder === 0 ? 0 : remainder + 1);
+}
+
+function invitationFieldLength(value: string, path: readonly (string | number)[]): string {
+  const length = value.length;
+  if (length > 0xfff) fail('Invitation field is too long.', path);
+  return length.toString(16).padStart(INVITATION_LENGTH_HEX_DIGITS, '0');
+}
+
+function decodeInvitationField(
+  payload: string,
+  cursor: { value: number },
+  path: readonly (string | number)[],
+): string {
+  const lengthText = payload.slice(cursor.value, cursor.value + INVITATION_LENGTH_HEX_DIGITS);
+  if (!/^[0-9a-f]{3}$/.test(lengthText)) fail('Invitation field length is invalid.', path);
+  cursor.value += INVITATION_LENGTH_HEX_DIGITS;
+  const byteLength = Number.parseInt(lengthText, 16);
+  const encodedLength = encodedBase64UrlLength(byteLength);
+  const encoded = payload.slice(cursor.value, cursor.value + encodedLength);
+  if (encoded.length !== encodedLength) fail('Invitation field is truncated.', path);
+  cursor.value += encodedLength;
+  const decoded = decodeBase64UrlAscii(encoded, path);
+  if (decoded.length !== byteLength) fail('Invitation field length does not match its value.', path);
+  return decoded;
+}
+
+function canonicalInvitationEndpoint(value: unknown, path: readonly (string | number)[]): string {
+  const endpoint = boundedString(value, 1, 512, path);
+  type ParsedUrl = {
+    protocol: string;
+    origin: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    username: string;
+    password: string;
+  };
+  const UrlParser = (globalThis as unknown as { URL?: new (value: string) => ParsedUrl }).URL;
+  if (UrlParser === undefined) fail('Invitation endpoint URL parsing is unavailable.', path);
+  let parsed: ParsedUrl;
+  try {
+    parsed = new UrlParser(endpoint);
+  } catch {
+    fail('Invitation endpoint must be a valid URL.', path);
+  }
+  if (parsed.protocol !== 'https:' || !parsed.hostname || parsed.username || parsed.password ||
+      parsed.pathname !== '/' || parsed.search || parsed.hash || endpoint !== parsed.origin ||
+      (parsed.port !== '' && (Number.parseInt(parsed.port, 10) < 1 || Number.parseInt(parsed.port, 10) > 65_535))) {
+    fail('Invitation endpoint must be a canonical HTTPS origin.', path);
+  }
+  return endpoint;
+}
+
+function validateInvitationArtifact(value: unknown): InvitationArtifact {
+  const input = record(value);
+  exactKeys(input, ['version', 'endpoint', 'ca_spki_sha256', 'authority', 'secret', 'integrity'], [
+    'version',
+    'endpoint',
+    'ca_spki_sha256',
+    'authority',
+    'secret',
+    'integrity',
+  ]);
+  if (input.version !== INVITATION_ARTIFACT_VERSION) {
+    fail('Unsupported invitation artifact version.', ['version']);
+  }
+  const endpoint = canonicalInvitationEndpoint(input.endpoint, ['endpoint']);
+  const caSpkiSha256 = boundedString(input.ca_spki_sha256, 64, 64, ['ca_spki_sha256']);
+  if (!/^[0-9a-f]{64}$/.test(caSpkiSha256)) {
+    fail('CA SPKI SHA-256 must be lowercase hexadecimal.', ['ca_spki_sha256']);
+  }
+  if (input.authority !== 'client' && input.authority !== 'owner') {
+    fail('Invitation authority is invalid.', ['authority']);
+  }
+  return {
+    version: INVITATION_ARTIFACT_VERSION,
+    endpoint,
+    ca_spki_sha256: caSpkiSha256,
+    authority: input.authority,
+    secret: opaqueToken(input.secret, ['secret']),
+    integrity: opaqueToken(input.integrity, ['integrity']),
+  };
+}
+
+/**
+ * Return the canonical ASCII preimage for the artifact integrity binding.
+ * Implementations hash these exact bytes with their agreed secret algorithm;
+ * the shared package intentionally does not own a crypto runtime.
+ */
+export function getInvitationArtifactIntegrityInput(value: InvitationArtifact): string {
+  const artifact = validateInvitationArtifact(value);
+  const endpoint = encodeBase64UrlAscii(artifact.endpoint);
+  const secret = encodeBase64UrlAscii(artifact.secret);
+  return [
+    INVITATION_MAGIC,
+    invitationFieldLength(artifact.endpoint, ['endpoint']),
+    endpoint,
+    artifact.ca_spki_sha256,
+    artifact.authority === 'client' ? 'c' : 'o',
+    invitationFieldLength(artifact.secret, ['secret']),
+    secret,
+  ].join('');
+}
+
+/** Encode an invitation artifact as one canonical, unpadded base64url token. */
+export function encodeInvitationArtifact(value: InvitationArtifact): string {
+  const artifact = validateInvitationArtifact(value);
+  const payload = [
+    getInvitationArtifactIntegrityInput(artifact),
+    invitationFieldLength(artifact.integrity, ['integrity']),
+    encodeBase64UrlAscii(artifact.integrity),
+  ].join('');
+  const token = encodeBase64UrlAscii(payload);
+  if (token.length < 43 || token.length > 1024) {
+    fail('Encoded invitation artifact exceeds the supported token bound.');
+  }
+  return token;
+}
+
+/** Decode and strictly validate a canonical invitation artifact token. */
+export function decodeInvitationArtifact(value: unknown): InvitationArtifact {
+  const token = opaqueToken(value, ['invitation']);
+  const payload = decodeBase64UrlAscii(token, ['invitation']);
+  if (!payload.startsWith(INVITATION_MAGIC)) {
+    fail('Invitation uses an unsupported or legacy format.', ['invitation']);
+  }
+  const cursor = { value: INVITATION_MAGIC.length };
+  const endpoint = decodeInvitationField(payload, cursor, ['endpoint']);
+  const caSpkiSha256 = payload.slice(cursor.value, cursor.value + 64);
+  if (caSpkiSha256.length !== 64) fail('Invitation pin is truncated.', ['ca_spki_sha256']);
+  cursor.value += 64;
+  const authority = payload[cursor.value++];
+  const secret = decodeInvitationField(payload, cursor, ['secret']);
+  const integrity = decodeInvitationField(payload, cursor, ['integrity']);
+  if (cursor.value !== payload.length) fail('Invitation contains trailing fields.', ['invitation']);
+  return validateInvitationArtifact({
+    version: INVITATION_ARTIFACT_VERSION,
+    endpoint,
+    ca_spki_sha256: caSpkiSha256,
+    authority: authority === 'c' ? 'client' : authority === 'o' ? 'owner' : authority,
+    secret,
+    integrity,
+  });
+}
+
 function decodeRequestId(value: unknown, path: readonly (string | number)[]): string {
   const decoded = boundedString(value, 8, 128, path);
   if (!/^[A-Za-z0-9._-]+$/.test(decoded)) {

package/src/templates.ts

@@ -87,6 +87,16 @@ Review rounds:
 - After two blocked rounds, stop and ask the human before opening an exceptional round.
 - Findings outside the authorized outcome are reported separately and do not expand or gate the current work.`;
 
+export const COORDINATOR_FINDING_DISPATCH_DISCIPLINE = `
+
+Review dispatch:
+- A reviewer finding that carries an open ASK or an unverified condition is NOT dispatchable. Hold the rework until the ANSWER lands or the finding is withdrawn. Dispatch latency is seconds and verification is minutes, so routing a conditional finding guarantees that work starts before its premise is checked.`;
+
+export const REVIEWER_FINDING_DISCIPLINE = `
+
+Review findings:
+- Never post an unanswered ASK and the consequences that depend on it in the same entry. The ASK goes alone; the finding follows the answer. Labeling an entry "not a verdict" does not help: a post naming a path and a consequence is actionable on its face.`;
+
 export const RELEASE_CYCLE_SHAPES = `
 
 Integration and release:
@@ -136,6 +146,19 @@ Push discipline:
 - Push only the assigned branch after verifying the staged paths and final diff.
 - Do not force-push, rebase a shared branch, or publish from a local substitute artifact.`;
 
+export const SAME_REPOSITORY_WORKFLOW_DISCIPLINE = `
+
+Same-repository worktrees and handover:
+- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository are worktrees of the same clone family, sharing its object database and refs.
+- Start each new work item by switching branches in that seat's worktree with \`git checkout -b <branch>\`; never create a new worktree or folder per work item.
+- Create a branch only for a routed work item and announce its name in STARTING. One branch equals one work item and one owning seat; hand a branch to another seat only through an explicit log event.
+- Use merge-only history: no rebases and no force-pushes, because another seat may have the branch checked out or fetched.
+- Hand over a ref and exact commit SHA, never a filesystem path. Reviewers check out the SHA in their own worktree with \`git checkout --detach <SHA>\`; never read another seat's folder. Each review round binds to one exact SHA, and a new SHA restarts the gate sequence.
+- With a hosted origin, push the branch at creation with \`git push -u origin <branch>\`; a branch is cube-visible and REVIEW-READY only after that push.
+- With no hosted remote, the commit itself is the durable handover artifact because clone-family worktrees share refs; omit the push step. If push/fetch semantics are needed locally, use a local bare repository as the origin path.
+- Put all scratch work — detached review checkouts, clean-environment verification rigs, fake HOMEs, unpacked artifacts, and throwaway worktrees — under \`~/.borg/scratch/<your-seat-label>/\`; never use \`/tmp\` or an ad-hoc path. Scratch contents are disposable and must be cleaned up with the work.
+- After every merge to the protected or main branch, broadcast the merge SHA. When an origin exists, include \`git fetch origin && git merge origin/main\` as the merge-only sync instruction.`;
+
 export const UNIVERSAL_SAFETY_DISCIPLINES = [WAKE_PATH_MONITOR_DISCIPLINE];
 
 export const ROLE_SCOPED_SAFETY_DISCIPLINES = [
@@ -162,7 +185,7 @@ const SOFTWARE_DEV_DIRECTIVE = `## Scope and coordination
 - Reviewers assess the routed exact revision and do not create or expand work.
 - Waiting is valid when no authorized action is available.
 - Merge, deploy, publish, tag, release, credential, and live-operator actions require explicit authority.
-- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.`;
+- Keep cube-log signals concise. Put durable reasoning in the relevant issue, change, or existing maintained documentation only when it has an operational consumer.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`;
 
 const SOFTWARE_DEV_TAXONOMY: MessageTaxonomy = [
   {
@@ -262,7 +285,7 @@ Communication:
 - Distinguish read-only findings, proposals, completed actions, and actions awaiting authority.
 - Keep the primary playbook operational and concise. Delete obsolete, redundant, historical, cautionary, and example-heavy prose; do not relocate it into new runbooks, decisions, contracts, rationale, or case-study archives unless it has a current operational consumer.
 
-Builders implement; reviewers review; you coordinate. Integrate only when authorized.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${PUSH_DISCIPLINE_COORDINATOR}${DRONE_ADDRESSING_CONVENTION}`;
+Builders implement; reviewers review; you coordinate. Integrate only when authorized.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${PUSH_DISCIPLINE_COORDINATOR}${DRONE_ADDRESSING_CONVENTION}`;
 
 const BUILDER = `You implement only explicitly assigned software changes within the stated repository and slice.
 
@@ -306,7 +329,7 @@ Verdict:
 - Post one consolidated REVIEW-APPROVED or REVIEW-FEEDBACK bound to the exact revision.
 - Give file/line evidence and a bounded acceptance condition for blockers.
 - A new revision requires fresh review; never imply approval from a prior revision.
-- Do not merge, deploy, publish, tag, or release.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
+- Do not merge, deploy, publish, tag, or release.${REVIEWER_FINDING_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const RELEASE_QUALITY = `Perform only the routed release-quality checks for the exact software revision and changed surface.
 
@@ -316,7 +339,7 @@ const RELEASE_QUALITY = `Perform only the routed release-quality checks for the
 - Report reproducible failures with steps and evidence. Report passes with the exact scenarios exercised.
 - Label the verdict testing, docs, or both, and bind it to the exact revision.
 - Keep polish, unrelated drift, and optional improvements non-blocking and outside the current work unless explicitly assigned.
-- Do not merge, publish, deploy, tag, release, or create follow-up issues on your own.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
+- Do not merge, publish, deploy, tag, release, or create follow-up issues on your own.${REVIEWER_FINDING_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const PRODUCT_DESIGN = `Review only routed user-facing software changes or an explicit design request.
 
@@ -326,7 +349,7 @@ const PRODUCT_DESIGN = `Review only routed user-facing software changes or an ex
 - Create a mockup only when it materially resolves the authorized question; use repository-tracked, reviewable artifacts.
 - Give one consolidated approval or bounded blocker with observable evidence.
 - Do not redesign adjacent surfaces, set product strategy, implement code, create speculative artifacts, or open follow-up work without authorization.
-- Waiting is valid when no design review is routed.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
+- Waiting is valid when no design review is routed.${REVIEWER_FINDING_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const PRODUCT_STRATEGY = `Provide source-verified product analysis only when requested.
 
@@ -335,7 +358,7 @@ const PRODUCT_STRATEGY = `Provide source-verified product analysis only when req
 - Preserve uncertainty. A proposal is advisory and never authorizes implementation, reprioritization, or mutation.
 - Do not dispatch Builders, write implementation code, merge, release, or manufacture roadmap work from idle capacity.
 - Surface contradictions that materially affect the requested outcome; leave unrelated opportunities outside the active work.
-- Waiting is valid when no strategy question is assigned.${ESCALATION_DISCIPLINE}`;
+- Waiting is valid when no strategy question is assigned.${REVIEWER_FINDING_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const SECURITY_AUDITOR = `Perform only the routed security review of an exact software revision or an explicitly authorized security sweep.
 
@@ -344,7 +367,7 @@ const SECURITY_AUDITOR = `Perform only the routed security review of an exact so
 - Reproduce or source-prove findings. State preconditions, impact, severity, and the smallest acceptance condition.
 - One consolidated verdict per revision. Block only concrete in-scope or touched-surface security defects.
 - Report unrelated risks separately; do not expand the implementation, start a general hardening program, or create follow-up issues without authorization.
-- Do not implement fixes, merge, deploy, publish, tag, or release.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
+- Do not implement fixes, merge, deploy, publish, tag, or release.${REVIEWER_FINDING_DISCIPLINE}${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const SOFTWARE_DEV: Template = {
   ...NEW_CUBE_TEMPLATE_PRESENTATIONS[0],
@@ -469,7 +492,7 @@ const STARTER: Template = {
 - Assignment, review, and completion do not authorize unrelated work or integration.
 - ACK is receipt only; STARTING or substantive PROGRESS confirms activation.
 - Findings outside scope are reported, not automatically fixed.
-- Waiting is valid when no authorized action is available.`,
+- Waiting is valid when no authorized action is available.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`,
   message_taxonomy: STARTER_TAXONOMY,
   roles: [
     {
@@ -485,7 +508,7 @@ const STARTER: Template = {
 - Questions, findings, proposals, open queues, and spare capacity do not authorize new work.
 - Route completed work to the Reviewer only when review is required.
 - Ask the human before rescoping, abandoning, waiving, merging, shipping, publishing, or taking an irreversible action unless already delegated.
-- Waiting is valid when work is complete, blocked, under review, or awaiting authority.${ANTI_PASSIVE_STANDING_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}`,
+- Waiting is valid when work is complete, blocked, under review, or awaiting authority.${COORDINATOR_FINDING_DISPATCH_DISCIPLINE}${ANTI_PASSIVE_STANDING_DISCIPLINE}${DRONE_ADDRESSING_CONVENTION}`,
     },
     {
       name: 'Worker',
@@ -510,7 +533,7 @@ const STARTER: Template = {
 - Check correctness, completeness, regressions, and scope containment proportionate to the task.
 - Post one APPROVED or FEEDBACK verdict. Give concrete evidence and a bounded acceptance condition for blockers.
 - Keep unrelated observations outside the current work. Do not implement fixes, expand scope, integrate, publish, or take irreversible actions.
-- Waiting is valid when no review is routed.${ESCALATION_DISCIPLINE}`,
+- Waiting is valid when no review is routed.${REVIEWER_FINDING_DISCIPLINE}${ESCALATION_DISCIPLINE}`,
     },
   ],
 };
@@ -591,7 +614,7 @@ const LOCAL_MODEL_DIRECTIVE = `## Verification-cost workflow
 - A fourth seat is optional: add a second Executor when throughput-bound, or a second capable Director as an independent review lens when correctness-bound. Never use a cheap model as a review lens.
 - Waiting is valid only when no authorized action or active assigned work remains, or while a role is awaiting a named predecessor and has no independent action it can advance.
 - Dispatch, packet echo, status, and answers are not completion. Each role continues its active item in the same turn until it posts a terminal signal from its own vocabulary.
-- Merge, publish, deploy, tag, release, credential, and irreversible actions require explicit authority.`;
+- Merge, publish, deploy, tag, release, credential, and irreversible actions require explicit authority.${SAME_REPOSITORY_WORKFLOW_DISCIPLINE}`;
 
 const LOCAL_MODEL_DIRECTOR = `You own authorized intent, priorities, decisions, and verification that requires careful reading. Never implement a change.