broker: migrate runtime registration identity to org id

[benvinegar]

Summary

• migrate broker registration CLI from workspace-focused input to org-focused input (--org-id)
• keep --workspace-id as a backward-compatible alias and keep legacy env aliases populated for migration
• update gateway bridge runtime to resolve org identity, send both org_id and workspace_id on wire calls, and accept either on inbound envelopes
• update startup/doctor/install/runtime broker-mode detection to support org-id-first config
• update docs/schema/runbooks and tests for org-id terminology + compatibility behavior

Validation

• npm run lint:js
• npm run test:js
• npm run lint:shell
• npm run test:shell
• npm test

Important Follow-up (Server)

This PR is the client/runtime compatibility layer. A broker server PR is still required to complete the migration:

• treat org_id as canonical for /api/register, /api/inbox/pull, /api/inbox/ack, and /api/send
• emit/sign envelopes using org identity
• keep temporary workspace_id compatibility during rollout

[greptile-apps]

Greptile Summary

This PR successfully migrates broker registration from workspace-focused identity (--workspace-id) to org-focused identity (--org-id) while maintaining comprehensive backward compatibility.

Key Changes

• CLI Migration: bin/broker-register.mjs now uses --org-id as primary parameter, with --workspace-id accepted as a backward-compatible alias
• Validation Updates: Replaced Slack team ID regex (/^T[A-Z0-9]+$/) with flexible org ID pattern (/^[A-Za-z0-9][A-Za-z0-9._:-]*$/) supporting both legacy workspace IDs and new org identifiers
• Runtime Resolution: gateway-bridge/env-aliases.mjs intelligently resolves org identity from both GATEWAY_BROKER_ORG_ID/SLACK_BROKER_ORG_ID and legacy *_WORKSPACE_ID variants, populating both keys for compatibility
• Wire Protocol: Both org_id and workspace_id are sent in all broker API calls (/api/register, /api/inbox/pull, /api/inbox/ack, /api/send) to support older broker servers during rollout
• Envelope Handling: Inbound message verification accepts either org_id or workspace_id from broker envelopes, using the provided routing ID for signature canonicalization
• Infrastructure Updates: Shell scripts (doctor.sh, baudbot-runtime.sh, config.sh) updated to recognize org ID configuration while maintaining workspace ID fallback checks
• Documentation: All docs, schemas, and runbooks updated to reflect org-first terminology with clear deprecation notices

Validation

Comprehensive test coverage validates:

• CLI argument parsing and aliasing
• Org ID validation (including legacy Slack team IDs)
• Environment variable resolution precedence
• Wire protocol compatibility (both fields sent/accepted)
• Integration test scenarios with real broker protocol exchanges

Migration Strategy

The implementation follows a safe multi-phase rollout:

1. Phase 1 (this PR): Client supports both identifiers, sends both on wire
2. Phase 2 (server): Broker treats org_id as canonical, maintains workspace_id compatibility
3. Phase 3 (future): Deprecate workspace ID after full migration

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The migration is exceptionally well-executed with comprehensive backward compatibility, thorough test coverage (unit, integration, and shell tests all passing), and a carefully designed rollout strategy. All critical paths maintain dual support for both org_id and workspace_id identifiers, ensuring zero-downtime migration.
• No files require special attention

Important Files Changed

Filename	Overview
bin/broker-register.mjs	Migrated CLI from --workspace-id to --org-id with backward-compatible aliasing, updated validation regex, and ensured both fields are sent on wire for server compatibility
gateway-bridge/broker-bridge.mjs	Updated to use SLACK_BROKER_ORG_ID as canonical identity, accept either org_id or workspace_id on inbound envelopes, and send both on outbound requests
gateway-bridge/env-aliases.mjs	Added resolution logic to populate SLACK_BROKER_ORG_ID from legacy workspace ID env vars with deprecation warnings, maintaining both keys for runtime compatibility
bin/broker-register.test.mjs	Updated tests to validate org ID format, verify --workspace-id CLI alias, and confirm both org_id and workspace_id are sent in registration payload
test/broker-bridge.integration.test.mjs	Migrated all test fixtures to use SLACK_BROKER_ORG_ID and added assertions to verify both org_id and workspace_id are sent in requests
bin/lib/baudbot-runtime.sh	Updated broker mode detection to check for both org ID and workspace ID env vars for backward compatibility
bin/doctor.sh	Modified broker mode validation to accept either org ID or workspace ID, removed workspace ID from strict requirement list
.env.schema	Added GATEWAY_BROKER_ORG_ID and SLACK_BROKER_ORG_ID with clear deprecation annotations for workspace ID variants

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client/CLI] -->|--org-id or --workspace-id| B[broker-register.mjs]
    B -->|Normalizes to orgId| C[Registration Payload]
    C -->|Sends both org_id and workspace_id| D[Broker Server /api/register]
    
    E[Runtime Startup] -->|Reads env vars| F[env-aliases.mjs]
    F -->|Resolves GATEWAY/SLACK variants| G{Has ORG_ID?}
    G -->|Yes| H[Use ORG_ID]
    G -->|No| I{Has WORKSPACE_ID?}
    I -->|Yes| J[Fallback to WORKSPACE_ID]
    I -->|No| K[Error: Missing Config]
    J -->|Populate both keys| L[Runtime Config]
    H -->|Populate both keys| L
    
    L --> M[broker-bridge.mjs]
    M -->|brokerOrgId variable| N[Wire Protocol]
    N -->|Outbound: sends both org_id and workspace_id| O[Broker API]
    N -->|Inbound: accepts org_id or workspace_id| P[Envelope Verification]
    P -->|Uses routing ID for signature| Q[Message Processing]
    
    style C fill:#e1f5ff
    style L fill:#e1f5ff
    style N fill:#fff4e1
    style P fill:#e7ffe1

Loading

_{Last reviewed commit: 6933b0c}