openmoq · mondain · Jul 2, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -143,6 +143,7 @@ if(OPENMOQ_ENABLE_PICOQUIC AND EXISTS "${OPENMOQ_PICOQUIC_SOURCE_DIR}/CMakeLists
 endif()
 
 add_library(openmoq_publisher_lib STATIC
+    src/cat4moq.cpp
     src/cli_options.cpp
     src/cmaf_segmenter.cpp
     src/cmsf_packager.cpp
@@ -207,6 +208,12 @@ add_executable(openmoq-publisher-psychedelic-example
 )
 target_link_libraries(openmoq-publisher-psychedelic-example PRIVATE openmoq_publisher_lib)
 
+add_executable(openmoq-publisher-auth-example
+    examples/auth/AuthPublisher.cpp
+    examples/auth/catapult_client.cpp
+)
+target_link_libraries(openmoq-publisher-auth-example PRIVATE openmoq_publisher_lib)
+
 include(CTest)
 
 if(OPENMOQ_BUILD_TESTS)
@@ -246,6 +253,18 @@ if(OPENMOQ_BUILD_TESTS)
     target_link_libraries(openmoq-publisher-api-tests PRIVATE openmoq_publisher_lib)
     add_test(NAME openmoq-publisher-api-tests COMMAND openmoq-publisher-api-tests)
 
+    add_executable(openmoq-publisher-cat4moq-api-tests
+        tests/cat4moq_api_test.cpp
+    )
+    target_link_libraries(openmoq-publisher-cat4moq-api-tests PRIVATE openmoq_publisher_lib)
+    add_test(NAME openmoq-publisher-cat4moq-api-tests COMMAND openmoq-publisher-cat4moq-api-tests)
+
+    add_executable(openmoq-publisher-cat4moq-transport-token-tests
+        tests/cat4moq_transport_token_test.cpp
+    )
+    target_link_libraries(openmoq-publisher-cat4moq-transport-token-tests PRIVATE openmoq_publisher_lib)
+    add_test(NAME openmoq-publisher-cat4moq-transport-token-tests COMMAND openmoq-publisher-cat4moq-transport-token-tests)
+
     add_executable(openmoq-publisher-control-message-tests
         tests/moqt_control_messages_test.cpp
     )

diff --git a/README.md b/README.md
@@ -151,6 +151,7 @@ On Windows, replace `./build/openmoq-publisher` with `build\Release\openmoq-publ
 | FFmpeg input recipes | [docs/ffmpeg.md](docs/ffmpeg.md) |
 | Relay interoperability | [docs/relay-interop.md](docs/relay-interop.md) |
 | C++ Publisher API | [docs/publisher-api.md](docs/publisher-api.md) |
+| CAT4MOQ auth example | [examples/auth/README.md](examples/auth/README.md) |
 | Protocol mapping | [docs/protocol-mapping.md](docs/protocol-mapping.md) |
 | WebTransport compliance | [docs/webtransport-compliance.md](docs/webtransport-compliance.md) |
 | Transport plan | [docs/transport-plan.md](docs/transport-plan.md) |

diff --git a/docs/publisher-api.md b/docs/publisher-api.md
@@ -13,6 +13,7 @@ Key types:
 - `openmoq::publisher::PublisherConfig`
 - `openmoq::publisher::Publisher`
 - `openmoq::publisher::PreparedPublish`
+- `openmoq::publisher::cat4moq::AuthorizationConfig`
 
 ## 2. Link the Library
 
@@ -52,7 +53,36 @@ config.subscriber_timeout = std::chrono::seconds(30);
 openmoq::publisher::Publisher publisher(config);
 ```
 
-## 4. Prepare Media Once (Batch Mode)
+## 4. Optional CAT4MOQ Authorization
+
+Applications that need CAT4MOQ or other MoQ authorization-token carriage configure tokens at the public API layer. Transport internals consume this config when encoding setup, namespace, and publish request messages.
+
+```cpp
+#include "openmoq/publisher/cat4moq.h"
+#include "openmoq/publisher/publisher_api.h"
+
+std::vector<std::uint8_t> setup_cwt = read_setup_token();
+std::vector<std::uint8_t> publish_cwt = read_publish_token();
+
+openmoq::publisher::PublisherConfig config;
+config.authorization.setup_token =
+    openmoq::publisher::cat4moq::wrap_cat_token(setup_cwt);
+config.authorization.action_token =
+    openmoq::publisher::cat4moq::wrap_cat_token(publish_cwt);
+```
+
+`setup_token` is carried on the session setup message. `action_token` is carried on publisher action requests such as namespace publish and track publish. Leave either field empty when that part of the relay policy does not require a token.
+
+Helper wrappers:
+
+- `wrap_cat_token(...)`: wraps raw Catapult/CAT CWT bytes as a CAT authorization-token value.
+- `wrap_out_of_band_token(...)`: wraps raw private token bytes with the out-of-band token type.
+- `AuthorizationToken`: stores the encoded authorization-token value sent on the wire.
+- `AuthorizationConfig`: groups setup-level and action-level tokens for `PublisherConfig`.
+
+The runnable example in [examples/auth](../examples/auth/README.md) shows file-based tokens, Catapult command integration, and a deterministic `publish_live_objects(...)` flow against a moqx relay.
+
+## 5. Prepare Media Once (Batch Mode)
 
 For file or buffered stream workflows, prepare media first:
 
@@ -78,7 +108,7 @@ This is useful for larger apps that want to:
 - store plan state
 - publish the same prepared asset to multiple endpoints
 
-## 5. Optional: Inspect or Emit the Plan
+## 6. Optional: Inspect or Emit the Plan
 
 Render the plan for logging/debug:
 
@@ -92,7 +122,7 @@ Emit generated catalog and media objects to disk:
 publisher.emit_objects(prepared, "out");
 ```
 
-## 6. Configure Endpoint and TLS
+## 7. Configure Endpoint and TLS
 
 Build `EndpointConfig` and optional `TlsConfig`.
 
@@ -126,7 +156,7 @@ tls.insecure_skip_verify = false;
 // tls.private_key_path = "...";
 ```
 
-## 7. Publish Prepared Content
+## 8. Publish Prepared Content
 
 Use prepared content plus endpoint:
 
@@ -149,7 +179,7 @@ Convenience helpers:
 - `publish_file(path, endpoint, tls)`
 - `publish_stream(input, source_name, endpoint, tls)`
 
-## 8. Live Input Publish (Incremental stdin/stream)
+## 9. Live Input Publish (Incremental stdin/stream)
 
 The default live path expects fragmented MP4, which matches ffmpeg/CMAF
 pipelines:
@@ -168,7 +198,7 @@ if (!status.ok) {
 
 `publish_live(...)` uses incremental parsing and live publish flow instead of buffering to EOF.
 
-## 9. Arbitrary Live Object Publish
+## 10. Arbitrary Live Object Publish
 
 Applications that already produce MoQ objects directly can bypass fragmented MP4
 ingest with `publish_live_objects(...)`.
@@ -200,7 +230,7 @@ Each `LiveObject` supplies the target track, group/object IDs, optional media
 timing, and the payload bytes to send. The fragmented MP4 `publish_live(...)`
 API remains the default live publishing path.
 
-## 10. ALPN Override Behavior
+## 11. ALPN Override Behavior
 
 By default, the API applies transport-appropriate ALPN:
 
@@ -229,7 +259,7 @@ The same override flag exists on:
 - `publish_live(...)`
 - `publish_live_objects(...)`
 
-## 11. Error Handling Pattern
+## 12. Error Handling Pattern
 
 All API publish calls return `TransportStatus`:
 
@@ -251,7 +281,7 @@ if (!status.ok) {
 }
 ```
 
-## 12. Integration Pattern for Larger Applications
+## 13. Integration Pattern for Larger Applications
 
 For service-style integration:
 
@@ -263,7 +293,7 @@ For service-style integration:
 6. For direct object producers, provide a `LiveObjectSource` and call `publish_live_objects(...)`.
 7. Use `TransportStatus` messages for metrics and retry decisions.
 
-## 13. Publish Summary (`stats`)
+## 14. Publish Summary (`stats`)
 
 The publisher API is blocking: `publish(...)`, `publish_file(...)`,
 `publish_stream(...)`, and `publish_live(...)` run the session on the calling
@@ -332,7 +362,7 @@ Example:
 }
 ```
 
-## 14. Complete Example
+## 15. Complete Example
 
 ```cpp
 #include "openmoq/publisher/publisher_api.h"
@@ -378,7 +408,7 @@ int main() {
 }
 ```
 
-## 15. Live Publish with Audio/Video Encoders on Other Threads
+## 16. Live Publish with Audio/Video Encoders on Other Threads
 
 `publish_live(...)` consumes one MP4 byte stream.  
 For multi-track live publishing, the common pattern is:

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -107,6 +107,33 @@ cat sample.mp4 | ./build/openmoq-publisher \
   --insecure
 ```
 
+## CAT4MOQ Auth Example
+
+Build the CAT4MOQ auth example when testing a relay that requires MoQ authorization tokens:
+
+```bash
+cmake --build build --target openmoq-publisher-auth-example
+```
+
+Run it with a token file:
+
+```bash
+CAT4MOQ_TOKEN_FILE=/tmp/publish-token.cwt \
+CAT4MOQ_ENDPOINT='https://127.0.0.1:4433/moq-relay' \
+./examples/auth/run-cat4moq-auth-example.sh
+```
+
+Or run it with moqx as the Catapult/CAT4MOQ issuer command:
+
+```bash
+CATAPULT_CAT4MOQ_COMMAND='../moqx/build/moqx issue-cat-token --config /tmp/moqx-auth.yaml --auth-service live --auth-key-id cat-dev --auth-actions client_setup,publish_namespace,publish --auth-namespace {namespace} --auth-track {track}' \
+CAT4MOQ_ENDPOINT='https://127.0.0.1:4433/moq-relay' \
+./examples/auth/run-cat4moq-auth-example.sh
+```
+
+See [examples/auth/README.md](../examples/auth/README.md) for the moqx auth
+config, token generation, relay connection, and focused-test workflow.
+
 ## Output Notes
 
 - default output includes the `catalog` object plus media objects

diff --git a/docs/relay-interop.md b/docs/relay-interop.md
@@ -71,6 +71,49 @@ OPENMOQ_PICOQUIC_TRACE=1 ./build/openmoq-publisher \
 
 `moq-relay.red5.net:4433` currently accepts WebTransport on `/moq`; `/moq-relay` returns HTTP `404` during CONNECT. The moqx relay examples use a placeholder hostname because those relay hostnames are not public yet; moqx uses `/moq-relay`.
 
+## CAT4MOQ Authorization with moqx
+
+For moqx services with auth enabled, use the auth example instead of the generic CLI. It obtains CAT4MOQ token bytes from a file or Catapult command, configures `PublisherConfig::authorization`, and publishes a deterministic live-object track.
+
+Build the example:
+
+```bash
+cmake --build build --target openmoq-publisher-auth-example
+```
+
+Run against an already-started relay:
+
+```bash
+CAT4MOQ_TOKEN_FILE=/tmp/publish-token.cwt \
+CAT4MOQ_ENDPOINT='https://127.0.0.1:4433/moq-relay' \
+CAT4MOQ_NAMESPACE='cat4moq.example' \
+CAT4MOQ_TRACK='video' \
+./examples/auth/run-cat4moq-auth-example.sh
+```
+
+Run with separate setup/action tokens:
+
+```bash
+CAT4MOQ_SETUP_TOKEN_FILE=/tmp/setup.cwt \
+CAT4MOQ_ACTION_TOKEN_FILE=/tmp/publish.cwt \
+CAT4MOQ_ENDPOINT='https://127.0.0.1:4433/moq-relay' \
+./examples/auth/run-cat4moq-auth-example.sh
+```
+
+Run with moqx as the Catapult/CAT4MOQ issuer command:
+
+```bash
+CATAPULT_CAT4MOQ_COMMAND='../moqx/build/moqx issue-cat-token --config /tmp/moqx-auth.yaml --auth-service live --auth-key-id cat-dev --auth-actions client_setup,publish_namespace,publish --auth-namespace {namespace} --auth-track {track}' \
+CAT4MOQ_ENDPOINT='https://127.0.0.1:4433/moq-relay' \
+./examples/auth/run-cat4moq-auth-example.sh
+```
+
+When using the default CAT wrapper, configure moqx service auth with
+`token_type: 16`, matching the token type wrapped by moqxr. If using
+`CAT4MOQ_TOKEN_WRAPPER=out-of-band`, configure `token_type: 0`. See
+[examples/auth/README.md](../examples/auth/README.md) for the local moqx auth
+config, token generation, token encoding, and focused-test workflow.
+
 ## Trace CSV
 
 If you want a per-object CSV trace for pacing and enqueue correlation, set `OPENMOQ_PICOQUIC_TRACE_CSV` alongside `OPENMOQ_PICOQUIC_TRACE`: