feat(session): authenticate Hunk broker clients

[benvinegar]

Summary

• define Hunk’s fixed dev.hunk Phase-1 contract and owner-private Ed25519 credential discovery
• authenticate producer WebSockets before registration and distinguish scoped register/reconnect ownership
• negotiate short-lived caller sessions, sign exact CLI requests, and verify bounded signed responses
• protect Hunk capabilities and /session-api while preserving independent browser-review capabilities
• expose liveness-only public health and remove unverifiable PID-based daemon replacement
• bound incomplete handshakes across upgrade, hello, and registration on Node and Bun

Security properties

• no unauthenticated producer registration or raw session control transition
• Host and Origin checks remain outermost
• producer expiry/revocation is rechecked and stale owners are retired
• target selectors bind to one session ID before authorization and execution
• authenticated reconnect atomically rejects uncertain work and retires the old peer
• browser-review credentials cannot authorize generic session controls, or vice versa

Validation

• 1,828 unit/integration tests passed; 7 skipped
• 135 PTY tests passed; 1 platform skip
• 9 TTY smoke tests passed
• real Node adapter suite passed
• typecheck, lint, dependency boundaries, formatting, and diff checks passed
• independent final security review found no blocker/high regression

Stack

• Depends on fix(session): bound broker scheduling and transport #904, fix(session): validate broker runtime boundaries #903, feat(session): add signed broker authorization #901, and fix(session): bind broker state to peer ownership #898
• Completes the five-PR Phase-1 implementation stack
• Durable candidate-key rotation and native Windows DACL/reparse validation remain explicit publication gates

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored		Aug 29, 2026 7:35pm

[greptile-apps]

Greptile Summary

This PR adds owner-private Ed25519 credentials and authenticated producer, reconnect, and CLI request flows to the local Hunk session broker. It also bounds incomplete handshakes, narrows public health output, and removes unverifiable PID-based daemon replacement.

• Adds challenge/proof producer authentication and signed caller request/response sessions.
• Enforces operation, command, session, and reconnect ownership scopes.
• Adds credential discovery, filesystem validation, and atomic credential creation.
• Coordinates authenticated reconnect replacement with pending-work rejection.
• Adds Node and Bun handshake timers and unauthenticated-socket budgets.
• Updates daemon startup, capabilities, documentation, and integration coverage.

Confidence Score: 4/5

The PR appears safe to merge after the non-blocking new-module filename convention issue is addressed.

The authentication, authorization, replay prevention, reconnect ownership, credential storage, and handshake lifecycle paths reviewed retain their intended boundaries; the only accepted concern is the nonconforming filename of the new client-authentication module.

Files Needing Attention: packages/session-broker/src/clientAuthentication.ts

Important Files Changed

Filename	Overview
packages/session-broker/src/authentication.ts	Implements bounded producer challenges and short-lived caller authentication with transcript signatures, replay controls, and active-grant checks.
packages/session-broker/src/clientAuthentication.ts	Implements producer and caller authentication clients correctly, but the new module filename violates the required dash-case convention.
packages/session-broker/src/daemon.ts	Gates producer state changes behind authentication and resolves caller targets before authorization and execution.
packages/session-broker-core/src/brokerState.ts	Adds atomic owner replacement while transferring reservations and rejecting work tied to the retired socket.
src/session/broker/credentials.ts	Adds strict credential parsing, owner-private path validation, no-follow reads, and atomic concurrent credential publication.
src/session/broker/brokerServer.ts	Composes Hunk-specific grants, authorization facts, signed responses, and the authenticated daemon surface.
src/session/broker/brokerClient.ts	Loads producer credentials and connects through the authenticated producer handshake and scoped reconnect path.
src/session/agent/cliClient.ts	Negotiates short-lived caller sessions and verifies signed, request-bound daemon responses.
packages/session-broker-bun/src/serve.ts	Bounds unauthenticated Bun WebSocket peers with handshake timers and releases admission after authentication.
packages/session-broker-node/src/serve.ts	Adds equivalent handshake admission and timeout lifecycle handling to the Node adapter.

Sequence Diagram

sequenceDiagram
    participant Producer as Hunk producer
    participant Broker as Session broker
    participant CLI as Hunk CLI
    participant App as Live session

    Producer->>Broker: hello-init
    Broker-->>Producer: signed challenge
    Producer->>Broker: signed proof
    Broker-->>Producer: authenticated acknowledgement
    Producer->>Broker: register or reconnect
    Broker->>Broker: Validate scope and bind owner
    Broker-->>Producer: Registration accepted

    CLI->>Broker: Negotiate caller session
    Broker-->>CLI: Short-lived caller session
    CLI->>Broker: Signed session-api request
    Broker->>Broker: Verify freshness, scope, and target
    Broker->>App: Dispatch authorized command
    App-->>Broker: Command result
    Broker-->>CLI: Bounded signed response

Loading

Prompt To Fix All With AI

### Issue 1
packages/session-broker/src/clientAuthentication.ts:1
**CamelCase module filename**

The new `clientAuthentication.ts` module conflicts with the repository’s enforced dash-case filename convention, requiring its package export, production import, and colocated test to retain a nonconforming path. Rename the module and corresponding test to `client-authentication.ts` and update their imports.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(session): authenticate Hunk broker ..." | Re-trigger Greptile}

[greptile-apps]

CamelCase module filename

The new clientAuthentication.ts module conflicts with the repository’s enforced dash-case filename convention, requiring its package export, production import, and colocated test to retain a nonconforming path. Rename the module and corresponding test to client-authentication.ts and update their imports.

Context Used: guidelines.mdc Cursor rule (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/session-broker/src/clientAuthentication.ts
Line: 1

Comment:
**CamelCase module filename**

The new `clientAuthentication.ts` module conflicts with the repository’s enforced dash-case filename convention, requiring its package export, production import, and colocated test to retain a nonconforming path. Rename the module and corresponding test to `client-authentication.ts` and update their imports.

**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!