borgmcp-shared 0.4.0 → 0.4.2

package/src/protocol/contract.ts

@@ -2,7 +2,7 @@ import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.4.0' as const;
+export const SHARED_PACKAGE_VERSION = '0.4.2' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
@@ -14,9 +14,22 @@ export const PROTOCOL_HTTP_CONTRACT = {
   protocol: { method: 'GET', path: PROTOCOL_INFO_PATH, authenticated: false, success_status: 200 },
   enrollment: { method: 'POST', path: ENROLLMENT_EXCHANGE_PATH, authenticated: 'invitation', success_status: 201 },
   cubes: { method: 'POST', path: CUBES_PATH, authenticated: true, success_status: 201 },
+  drone_reassign: {
+    method: 'PATCH',
+    path: '/api/cubes/:cubeId/drones/:droneId',
+    authenticated: true,
+    success_status: 200,
+  },
+  drone_evict: {
+    method: 'DELETE',
+    path: '/api/cubes/:cubeId/drones/:droneId',
+    authenticated: true,
+    success_status: 200,
+  },
   auth_missing_status: 401,
   auth_invalid_status: 401,
   cursor_expired_status: 410,
+  drone_evicted_status: 410,
   content_too_large_status: 413,
   unsupported_protocol_status: 426,
   redirect_policy: 'error',

package/src/protocol/coordination.ts

@@ -38,6 +38,28 @@ export interface ReadLogResult {
   claims: ClaimRecord[];
 }
 
+export interface ReassignDroneRequest {
+  role_id: string;
+}
+
+export interface ManagedDrone {
+  id: string;
+  cube_id: string;
+  role_id: string;
+  label: string;
+}
+
+export interface ReassignDroneResult {
+  drone: ManagedDrone;
+}
+
+export type EvictDroneRequest = Record<string, never>;
+
+export interface EvictDroneResult {
+  drone_id: string;
+  evicted: true;
+}
+
 function object(value: unknown): Record<string, unknown> {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     throw new ProtocolContractError('Expected a coordination object.');
@@ -84,6 +106,66 @@ function positiveInteger(value: unknown, name: string, maximum: number): number
   return decoded;
 }
 
+function decodeManagedDrone(value: unknown): ManagedDrone {
+  const input = object(value);
+  exact(input, ['id', 'cube_id', 'role_id', 'label'], ['id', 'cube_id', 'role_id', 'label']);
+  return {
+    id: decodeUuid(input.id, ['id']),
+    cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    role_id: decodeUuid(input.role_id, ['role_id']),
+    label: boundedString(input.label, 'label', 120),
+  };
+}
+
+export function decodeReassignDroneRequest(value: unknown): ReassignDroneRequest {
+  const input = object(value);
+  exact(input, ['role_id'], ['role_id']);
+  return { role_id: decodeUuid(input.role_id, ['role_id']) };
+}
+
+export function decodeReassignDroneRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<ReassignDroneRequest> {
+  return decodeProtocolEnvelope(value, decodeReassignDroneRequest);
+}
+
+export function decodeReassignDroneResult(value: unknown): ReassignDroneResult {
+  const input = object(value);
+  exact(input, ['drone'], ['drone']);
+  return { drone: decodeManagedDrone(input.drone) };
+}
+
+export function decodeReassignDroneResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<ReassignDroneResult> {
+  return decodeProtocolEnvelope(value, decodeReassignDroneResult);
+}
+
+export function decodeEvictDroneRequest(value: unknown): EvictDroneRequest {
+  const input = object(value);
+  exact(input, [], []);
+  return {};
+}
+
+export function decodeEvictDroneRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<EvictDroneRequest> {
+  return decodeProtocolEnvelope(value, decodeEvictDroneRequest);
+}
+
+export function decodeEvictDroneResult(value: unknown): EvictDroneResult {
+  const input = object(value);
+  exact(input, ['drone_id', 'evicted'], ['drone_id', 'evicted']);
+  if (input.evicted !== true) throw new ProtocolContractError('Invalid drone eviction result.');
+  return { drone_id: decodeUuid(input.drone_id, ['drone_id']), evicted: true };
+}
+
+export function decodeEvictDroneResultEnvelope(
+  value: unknown,
+): ProtocolEnvelope<EvictDroneResult> {
+  return decodeProtocolEnvelope(value, decodeEvictDroneResult);
+}
+
 export function decodeReadLogRequest(value: unknown): ReadLogRequest {
   const input = object(value);
   exact(input, ['cursor', 'limit'], ['cursor']);

package/src/templates.ts

@@ -242,9 +242,9 @@ The cube's release-cycle discipline has three documented shapes; the seat-holder
 **Frontend/web-UI testing-track dispatch instruction:** for PRs touching user-facing web UI bundles, explicitly instruct Release Quality in the dispatch: "load the built page in a browser, capture console output, and include it in RQ-APPROVED [testing]." Diff-only review routinely misses client-side bundle errors.
 
 **SR-exclusion list (autonomous-mode shape NOT eligible — explicit SR gate required regardless):**
-- PRs introducing new auth-bypass call sites (RLS-equivalent gates, admin-mode helpers)
-- PRs changing auth-decision caching mechanisms (subscription/session cache backend swaps)
-- PRs modifying OAuth or other identity-token handling (refresh flows, consent parameters)
+- PRs introducing new auth-bypass call sites (scoped-store gates, admin-mode helpers)
+- PRs changing authorization-decision caching mechanisms (session cache storage swaps)
+- PRs modifying identity or session-token handling (verification, renewal, revocation)
 - PRs touching CORS allowlist matching, encryption key handling, or webhook signature verification
 
 These exclusions reflect the cube's documented threat model. Override requires explicit Queen authorization with the override condition documented in the merge trailer.
@@ -538,8 +538,7 @@ const SOFTWARE_DEV: Template = {
         'PD-APPROVED',
         'PS-APPROVED',
       ],
-      routing: 'directed',
-      default_to: ['coordinator', 'queen'],
+      routing: 'broadcast',
       lifecycle: 'completion',
     },
     {
@@ -671,7 +670,7 @@ Workflow:
 - Verify correctness: does the code do what the commit message claims? Tests pass? Bundle size acceptable? Follows project conventions?
 - **Verify implementation quality + suggest refactors when appropriate.** Beyond "does it work," ask: is the code clean and readable? Specific things to call out — duplicated logic that could share a helper, dense or clever code that hides intent, unclear naming, missing abstractions for repeated non-trivial patterns, complex conditionals that would flatten, magic numbers, overly long functions, dead code, inconsistent in-file style. **Balance against "don't over-engineer"**: per the project's standing rule, three similar lines is better than a premature abstraction. Refactors should reduce real complexity, not add layers for hypothetical future cases. Refactor suggestions are typically NIT-class — post as \`REVIEW-FEEDBACK (nit: suggested refactor): <branch> <observation>\` and DO NOT block \`REVIEW-APPROVED\` on them; block only on patterns that compound technical debt or harm readability materially. Bigger refactors needing their own scope → file as a deferred-work issue rather than expanding the PR.
 - **Replaced-module behavioral diff.** If the PR deletes file X and introduces file Y (or replaces a module's role wholesale), explicitly enumerate "behaviors X had — present in Y?" before approval. Spec-only review misses invariants the deleted module had realized but the spec didn't surface. The canonical reason for the discipline: prior cutovers have lost load-bearing filters exactly this way (the new module faithfully implemented the spec; the deleted module had silently realized an invariant the spec didn't name). Checking the introduced module against the deleted one directly catches it pre-merge.
-- **Security review is Security Auditor's lane, not yours.** If the PR touches auth, auth-scoped data access (RLS wrappers / session-bound query helpers), encryption, secret handling, webhook signature verification, input validation, CORS, rate limits, OAuth flows, or customer-data paths, surface that to the cube (e.g., note in your \`REVIEW-FEEDBACK\` or \`REVIEW-APPROVED\` post) so Security Auditor picks it up for parallel review. Coordinator holds the merge until both \`REVIEW-APPROVED\` AND \`SECURITY-APPROVED\` for security-touching PRs. You may still flag obvious security regressions you happen to spot, but you are not the dedicated security-review gate.
+- **Security review is Security Auditor's lane, not yours.** If the PR touches auth, scoped data access (scoped-store wrappers / session-bound query helpers), encryption, secret handling, input validation, origin allowlists, rate limits, credential flows, or sensitive-data paths, surface that to the cube (e.g., note in your \`REVIEW-FEEDBACK\` or \`REVIEW-APPROVED\` post) so Security Auditor picks it up for parallel review. Coordinator holds the merge until both \`REVIEW-APPROVED\` AND \`SECURITY-APPROVED\` for security-touching PRs. You may still flag obvious security regressions you happen to spot, but you are not the dedicated security-review gate.
 - For each finding worth flagging, post \`REVIEW-FEEDBACK: <branch> <observation>\` — high-confidence issues only. Sort blockers from nits explicitly.
 - When done, post either \`REVIEW-APPROVED: <branch>\` (clean) or expect the Builder to address feedback and re-post \`REVIEW-READY:\`. Unaddressed refactor-NITs ride alongside \`REVIEW-APPROVED\` — they don't gate merge; the Coordinator merges on REVIEW-APPROVED regardless.
 
@@ -751,12 +750,12 @@ Boundaries:
       detailed_description: `You are the cube's security specialist — the dedicated owner of the security expectations the project documents but no other role enforces. Other drones check correctness, behavior, experience, and performance; you check exploitability. Autonomous — coordinate through the log.
 
 Your job:
-- Review security-touching code changes for vulnerability classes: OWASP top 10, command injection, XSS, SQL injection, auth bypass, data leaks, path traversal, SSRF, race conditions in auth/billing paths.
-- Audit security-critical surfaces: auth flows (JWT/OAuth verification, JWKS caching), auth-scoped data access (any function that gates user-data access by session identity — RLS wrappers, session-bound query helpers, equivalent boundary guards), encryption (algorithms, key handling, IV/nonce uniqueness, secret storage), webhook signature verification (HMAC), input validation at API boundaries (Zod schemas or equivalent), CORS / origin allowlists, rate limiters, dependency hygiene (CVE checks on dependency bumps), customer-data and billing paths.
+- Review security-touching code changes for vulnerability classes: OWASP top 10, command injection, XSS, SQL injection, auth bypass, data leaks, path traversal, SSRF, and races in authorization or session state.
+- Audit security-critical surfaces: bearer and session verification, scoped data access (any function that gates data by session identity — scoped-store wrappers, session-bound query helpers, equivalent boundary guards), encryption (algorithms, key handling, IV/nonce uniqueness, secret storage), input validation at API boundaries (Zod schemas or equivalent), origin allowlists, rate limiters, dependency hygiene (CVE checks on dependency bumps), and sensitive local data paths.
 - Run periodic full-codebase sweeps separate from per-pull-request review — walk the documented security expectations (project security instructions, threat-model docs, security checklists) and verify they still hold. Cadence: once per minor release or every ~2 weeks, whichever comes first. Catches the "we documented it but stopped enforcing it" failure mode.
 
 When you engage on a PR:
-- On regen, scan the log for \`REVIEW-READY:\` signals on branches touching security surface (auth, auth-scoped data access, encryption, webhooks, input validation, CORS, rate limits, OAuth, customer-data paths, dependency bumps).
+- On regen, scan the log for \`REVIEW-READY:\` signals on branches touching security surface (auth, scoped data access, encryption, input validation, origin allowlists, rate limits, credential flows, sensitive-data paths, dependency bumps).
 - For non-security-relevant changes (experience copy, version bumps, test infrastructure, internal refactors of non-security code), DON'T gate. Code Reviewer alone is the merge gate for those.
 - Post \`STARTING: security review of <branch>\` and pull the diff.
 
@@ -812,8 +811,7 @@ const STARTER: Template = {
     {
       class: 'completion-gate',
       prefixes: ['APPROVED'],
-      routing: 'directed',
-      default_to: ['coordinator', 'queen'],
+      routing: 'broadcast',
       lifecycle: 'completion',
     },
     {