Skip to content

docs(ws-auth): experimental banner + LICENSE check (QoL sweep) #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
intel352 merged 1 commit into from
May 19, 2026
Merged

docs(ws-auth): experimental banner + LICENSE check (QoL sweep) #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 1 addition & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,3 @@
# workflow-plugin-ws-auth

WebSocket HMAC authentication plugin for the [workflow](https://github.com/GoCodeAlone/workflow) framework.

```
go get github.com/GoCodeAlone/workflow-plugin-ws-auth
```

## Features

- HMAC-SHA256 challenge-response handshake
- Per-connection key derivation via HKDF-SHA256
- Sequence-based replay protection
- JWT claim extraction (`player_type`, `sub`)
- Bidirectional connection <-> player mapping
- Constant-time signature comparison

## Auth Flow

```mermaid
sequenceDiagram
participant C as Client
participant S as Server

C->>S: WebSocket connect
S->>C: challenge {nonce, timestamp, server_id}
C->>S: handshake {signature, player_type, session_id, auth_token}
Note over S: Verify HMAC-SHA256 signature<br/>Extract JWT claims<br/>Derive per-connection key (HKDF)
S->>C: handshake_ok {hmac_key}
C->>S: signed message {seq, payload, signature}
Note over S: Verify HMAC + sequence
S->>C: response
```

## Configuration

Module type: `ws_auth.hmac`

```yaml
modules:
my_auth:
type: ws_auth.hmac
config:
shared_secret: "your-secret-key"
server_id: "my-server"
```

The shared secret can also be set via the `SDK_SECRET` environment variable (takes precedence over config).

## Pipeline Step

Step type: `step.ws_auth_identity`

Extracts the player ID from an authenticated WebSocket connection.

```yaml
steps:
- name: identify
type: step.ws_auth_identity
config:
connection_id: "{{.connectionId}}"
```

Output:
- `player_id` -- the authenticated player's ID
- `authenticated` -- boolean indicating whether the connection is authenticated

## Build & Test

```sh
go build ./...
go test ./...
```

Requires Go 1.26+ and depends on:
- `github.com/GoCodeAlone/workflow` v0.19.0
- `golang.org/x/crypto` (HKDF)

## License

[MIT](LICENSE)
> ⚠️ **Experimental** — This plugin compiles and passes its unit tests but has not been validated in any active GoCodeAlone-internal production deployment. Use with caution. Please [open an issue](https://github.com/GoCodeAlone/workflow-plugin-ws-auth/issues/new) if you adopt it so we can promote it to **verified** status.
Loading