Skip to content

feat(api): enforce communication token auth with public status subset - #175

Merged
Zoupers merged 14 commits into
VirtualBeingsResearch:mainfrom
Zoupers:fix/rest-communication-token
Aug 16, 2026
Merged

feat(api): enforce communication token auth with public status subset#175
Zoupers merged 14 commits into
VirtualBeingsResearch:mainfrom
Zoupers:fix/rest-communication-token

Conversation

@Zoupers

@Zoupers Zoupers commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR hardens Coworker API communication authentication while preserving the
previous local behavior until an administrator explicitly configures a
communication token.

Behavior:

  • No explicit API__COMMUNICATION_TOKEN: POST /messages, GET /status, and
    GET /logs/stream behave exactly as before. Desktop communication keeps the
    administrator-token fallback.
  • Explicit API__COMMUNICATION_TOKEN configured:
    • POST /messages requires Authorization: Bearer <token> (401 otherwise).
    • GET /status without a valid Bearer returns only basic lifecycle fields;
      a valid Bearer returns the full snapshot.
    • GET /logs/stream requires a valid Bearer.
    • Desktop registration, SSE, and WebSocket require the dedicated token.
  • The obsolete Coworker-side API__DEVELOPMENT_MODE setting has been removed;
    Desktop HTTPS enforcement remains controlled by Desktop's
    security.development_mode.

Implementation

  • src/coworker/api/routes.py: explicit-token flag separate from the effective
    token used for Desktop fallback; public/full /status branching; removed the
    _development_mode early return; token helper for other routes.
  • src/coworker/api/app.py: /logs/stream Bearer gate when a token is
    explicitly configured.
  • src/coworker/application.py: passes the explicit-token flag from config.
  • Web status page: token control and guidance appear only when the server
    reports an explicitly configured token; the back-face runtime log stream now
    uses an authenticated fetch stream and reconnects automatically.
  • Web admin Runtime Settings: api.communication_token has Generate and Copy
    token buttons. Generate creates a Relay-compatible
    cwct_v1_<32-byte-base64url> token; Copy fetches the effective token from the
    new GET /api/admin/communication-token endpoint and writes it to the
    clipboard. Saving hot-applies to the running API without a restart; .env
    changes still require a restart.
  • GET /profile is also gated once a token is explicitly configured, so an
    unauthenticated status page can no longer trigger profile-reminder inbox
    events as a side effect.
  • Updated the generated src/coworker/web/ assets via
    npm --prefix web run build.
  • Updated examples/chat.html, examples/api_test.html, and
    examples/api.py for Bearer support and partial-status guidance.
  • Updated paired Chinese/English docs, security policy, deployment,
    observability, upgrading, Desktop development, and configuration pages.

Validation

  • pytest (offline image): 1771 passed, 1 skipped
  • ruff check src tests examples/api.py: passed
  • mypy src: passed
  • npm --prefix web run build: passed
  • python scripts/check_version.py: passed
  • git diff --check: passed

Not run: Rust/Desktop checks (cargo, desktop npm tests) and Explore Lab
backend tests — no code in those areas changed.

Risks / compatibility

  • Breaking change only for installations that explicitly configure
    API__COMMUNICATION_TOKEN: REST integrations and the Web identity page must
    then provide the Bearer. The identity page and Web chat provide token inputs.
  • Installations without an explicitly configured token keep the previous
    unauthenticated local behavior; production deployments should configure
    API__COMMUNICATION_TOKEN.
  • The obsolete Coworker-side API__DEVELOPMENT_MODE setting has been removed.

@Zoupers Zoupers changed the title feat(api): require communication token for plain REST messages feat(api): require communication token for REST messages and status Aug 16, 2026
@Zoupers Zoupers changed the title feat(api): require communication token for REST messages and status feat(api): enforce communication token auth with public status subset Aug 16, 2026
@Zoupers
Zoupers added this pull request to the merge queue Aug 16, 2026
Merged via the queue into VirtualBeingsResearch:main with commit eb2b37b Aug 16, 2026
8 checks passed
@Zoupers
Zoupers deleted the fix/rest-communication-token branch August 16, 2026 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant