---
url: https://doc.moq.dev/draft/moq-hidden.md
description: >-
  This document defines an extension for MoQ Transport draft-ietf-moq-transport
  that hides namespaces from discovery.
---

# MoQ Hidden Extension

::: info
Rendered from the Internet-Draft source in this repository.
Submitted versions are on the [IETF datatracker](https://datatracker.ietf.org/doc/draft-lcurley-moq-hidden/).
:::

## Abstract

This document defines an extension for MoQ Transport [draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) that hides namespaces from discovery.
A namespace with a field starting with `.` below the prefix a subscriber asked for is left out of the advertisements it receives, unless its SUBSCRIBE\_NAMESPACE opts in.
A platform can then add internal namespaces, such as statistics, without them turning up in applications that list everything and use what they find.

## Note to Readers

This document was generated by an AI model from the implementation at [github.com/moq-dev/moq](https://github.com/moq-dev/moq) and is maintained alongside it.
Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.com/moq-dev/moq/pulls) if this spec sucks and you want to fix anything.

## Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) [RFC8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals, as shown here.

An endpoint **advertises** a namespace by sending PUBLISH\_NAMESPACE, or NAMESPACE in response to a SUBSCRIBE\_NAMESPACE.

A namespace is **hidden** from a subscription when one of its fields beyond the subscription's Track Namespace Prefix starts with the byte 0x2E (`.`).
A field inside the prefix never hides anything, so a prefix that names the hidden field itself lists what is under it, and a namespace at or above the prefix has no field beyond it.
Only the first byte counts: `catalog.v2` is not hidden.

## Introduction

Discovery in [draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) is all or nothing: a subscriber that asks for a prefix is told every namespace beneath it.
An application that asks for the empty prefix and plays what it finds breaks the moment its platform publishes anything else under the same root, like a relay's own statistics or internal routing state.

This extension reserves a leading `.` for such namespaces, as file systems do for hidden files.
A hidden namespace is still published, routed, and subscribed to like any other; it is only left out of discovery by default.
A subscriber that wants hidden namespaces too says so on the SUBSCRIBE\_NAMESPACE that would list them.

The name alone decides: there is no publisher-side flag, so a namespace cannot be hidden from one subscriber and listed to another under the same prefix.

## Setup Negotiation

An endpoint declares that it understands the HIDDEN parameter ([Opting In](#parameter)) with the following Setup Option ([draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) Section 10.3):

```
HIDDEN Setup Option {
  Option Key (vi64) = 0x40B5C
  Option Value (vi64) = 1
}
```

A receiver MUST ignore the value.
An endpoint MUST NOT send the HIDDEN parameter to a peer that did not declare this option, because an unknown parameter fails decoding.
A subscriber that wants hidden namespaces therefore waits for the peer's SETUP before sending SUBSCRIBE\_NAMESPACE.

The rest of this extension applies whether or not the peer declared the option: a peer that never heard of it never opts in, so it is never told about hidden namespaces.

## Opting In {#parameter}

A subscriber opts in to hidden namespaces with the following parameter on SUBSCRIBE\_NAMESPACE:

```
HIDDEN Parameter {
  Type (vi64) = 0x40B5E
  Value (vi64) = 0 or 1
}
```

A value of 1 opts in; 0 or an absent parameter does not.
A receiver MUST close the session with a PROTOCOL\_VIOLATION on any other value.

## Advertising {#advertising}

A publisher SHOULD NOT advertise a hidden namespace in response to a SUBSCRIBE\_NAMESPACE that did not opt in.
Hiding is a convenience for discovery, not access control, so a publisher MAY treat a subscriber it trusts, such as another relay in its own cluster, as opted in.

An unsolicited PUBLISH\_NAMESPACE answers no prefix, so it is measured against the empty one: a publisher SHOULD NOT send one for a hidden namespace.
When unsolicited advertisements are live, a SUBSCRIBE\_NAMESPACE is answered with only the namespaces they left out, which is to say those hidden from the empty prefix, that the subscription may see.
That covers both an opt-in and a prefix that names a hidden field itself, and no namespace is advertised twice.

Hiding narrows discovery and nothing else.
A SUBSCRIBE, FETCH, or TRACK\_STATUS for a track in a hidden namespace is served exactly as it would be without this extension.

## Security Considerations

A hidden namespace is not a secret.
Anyone who learns its name can subscribe to it, and a subscriber can opt in at will, so a publisher MUST apply the same authorization to hidden namespaces as to any other.

## IANA Considerations

This document requests the following registrations.
High, distinctive values are requested to avoid the low ranges reserved by [draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) and to minimize collisions with provisional registrations by other extensions.

### MOQT Setup Options

This document requests one registration in the "MOQT Setup Options" registry ([draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) Section 15.4), whose policy is Specification Required.

| Value   | Name   | Reference     |
|:--------|:-------|:--------------|
| 0x40B5C | HIDDEN | This Document |

### MOQT Message Parameters

This document requests one registration in the "MOQT Message Parameters" registry ([draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) Section 15.7).

| Value   | Name   | Carried In          | Reference     |
|:--------|:-------|:--------------------|:--------------|
| 0x40B5E | HIDDEN | SUBSCRIBE\_NAMESPACE | This Document |

Both values are even, so each is a bare varint.

## Normative References

* [draft-ietf-moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/)

## Acknowledgments

This document was drafted with the assistance of Claude, an AI assistant by Anthropic.