Roles and sharing-policy API

Routes, fields and refusal codes for roles and QoS. See Security model and trust boundaries for how roles and policy work, and Control which devices share with each other for the task.

Routes

Role and QoS writes share one policy revision:

1. Read the current ETag from GET /api/v1/peer-policy.
2. Send your write with If-Match: <ETag> and ?dry_run=1. Result: a confirm_token.
3. Send the same body again with confirm_token set, using the original ETag. Result: the write commits.

A token is bound to the revision and body it previewed. If another commit lands first, reread the ETag and preview again. See Automate with the API for a full worked session.

On /api/v1, a missing or expired browser session returns 401 console-session-required; sign in and preview again. On the private management listener, a missing or invalid management credential returns 401 management-authentication-required. A browser request also needs its current CSRF token.

Role fields and validation

Role names match ^[a-z0-9][a-z0-9._-]{0,31}$, and at most 256 roles may exist. default, quarantine, origin, seeder and legacy are reserved names.

Allow-list membership always falls back to tracker-only, independent of on_stale. peers must be a non-null array of unique role names. The role schema sets no per-role member cap, but the devices in one role still cannot exceed the devices in your inventory. A restricted role with origin: false is valid. origin_unreachable is an advisory the server returns when neither this role nor a permitted role can reach the origin. Every role and QoS object is closed and typed: an unknown key is refused.

nets accepts a bare IPv4 address or an IPv4 prefix with a decimal length, a netmask, or a hostmask; leading zeroes and IPv6 are refused. iris-role CSV import compares networks for you and keeps the first valid spelling.

A role's qos object cannot set defs.<role>.qos.on_stale: that fallback is a separate field on the role definition, not a QoS key. Stored ACLs, the older explicit per-device peer lists, hold at most 64 names with 256 rules each; a role's rules compile in memory and use none of those slots. One explicit stored-ACL assignment shadows a role rather than combining with it. iris-role migrate ACL ROLE --dry-run previews moving a device between them; iris-role migrate ACL ROLE --apply commits the move in two policy revisions. A quarantined device cannot be migrated. iris-role CSV import owns duplicate-network detection: it compares canonical networks while keeping the first valid spelling, and the raw policy validator does not promise duplicate-net rejection.

QoS keys

Values are integers. Rate keys are bytes per second, and 0 means unlimited; a nonzero rate must be at least 8,192 B/s. Numeric QoS values reject booleans. A key with a state overlay resolves in this order, most general to most specific: builtin → roles.qos_default → roles.qos_state_default.<state> → roles.defs.<role>.qos → roles.defs.<role>.qos_state.<state>. A partial state map overrides only the key it supplies; every other key keeps resolving through the rest of the chain.

max_peers, max_concurrent and the peer caps count connections; fanout is a multiplier; numwant counts peers per announce; handout_budget counts handouts per window; telemetry_every_ticks counts ticks; interval and cadence fields are seconds. Convert a decimal rate to the *_bps value with Mbit/s × 1,000,000 ÷ 8.

A PUT /api/v1/peer-policy/qos write replaces the whole selected QoS object; {} clears that layer. Omitting qos_state preserves the stored state object. An explicit qos_state: {} removes only the selected state layer and preserves the rest of the scalar QoS unchanged. A full role-definition replacement, a PUT .../roles/<name> write, must include qos_state to retain it: that write is a complete replacement, not a merge.

Role CSV uses seeder_numwant, leecher_numwant, seeder_announce_min_interval_s and leecher_announce_min_interval_s for the corresponding qos_state values. The same bounds apply. Export includes these columns; import replaces the whole definition, so blank or omitted cells remove those overrides.

Zero is unlimited, so no rate key expresses never upload. Use role membership and access rules to keep a role off a swarm, and account for connections aria2 already holds. The Console edits per-role QoS as typed fields and preserves tracker overlays. Global QoS uses PUT /api/v1/peer-policy/qos. There is no per-device QoS write route. Pair explanations come only from GET /api/v1/peer-policy/explain.

Scalar QoS is the instruction intent the server sends to a device. tracker_qos explains the selected tracker state and its sources. tracker_qos is tracker-only: tracker state never enters instruction QoS or control, telemetry, semantic hashes, role artifacts, stamps, serials, envelopes, heartbeat, or device configuration.

Response fields

GET /api/v1/peer-policy is count-only: it never returns the raw deny list, peer addresses, aria2 option dictionaries, session IDs, or the device IDs behind the mutual-origin preflight. Role drift (the gap between a device's declared role and its compiled membership) is the one exception: up to ten device IDs return, flagged if the list was truncated.

Devices can report different accepted revisions. A policy edit that leaves a device's effective settings unchanged does not by itself issue a new instruction.

Reviewed distribution access

The dedicated route has its own strong ETag, "origin-enforcement-<revision>". Keep it separate from the sharing-policy ETag.

1. Read GET /api/v1/peer-policy/origin-enforcement.

2. Send a PUT with that ETag in If-Match and this JSON body:

   {"mode":"enforce","max_new_ips":10,"max_new_devices":10,"if_policy_revision":1,"dry_run":true}
   

3. Check the counts and blockers. Send the unchanged request with dry_run: false and the returned confirm_token only after review.

Use the returned policy_revision, not the example value above. mode is preflight (Preview only in the Console) or enforce (Enforce reviewed blocks). Both budgets are integers from 0 to 1,000 and default to 10 on a new installation. new_ip_count and new_device_count are additions to the retained approval; retained_ip_count, proposed_ip_count and proposed_device_count describe the full proposed set. Counts are null when the required evidence is unavailable.

The confirmation binds exact device identities and addresses, not just their counts. Changed endpoints, policy, control revision or request fields require a new preview. Preview returns the proposed mode but does not apply it. Commit advances the control revision and returns pending with no applied proof.

GET separates requested mode from actual state. The Console labels these Saved mode and Transfer-service status at last refresh. Only enforced, with non-null applied counts, last_verified_at, no reason and no blockers, confirms recent application. The Console shows Blocks confirmed for that state. Proof expires after 120 seconds. Select Refresh status for current confirmation. review_required, degraded or unavailable needs attention; never interpret Approved for blocking as Confirmed at last refresh. Shared-address conflicts cannot be fully enforced with an IP blocklist. Switching to preflight uses the same review procedure.

Missing If-Match returns 428 precondition_required; a stale control marker returns 412 precondition_failed. A changed policy returns 409 policy_revision_conflict, a stale confirmation 409 origin_review_stale, and an unsafe apply 409 origin_enforcement_blocked. Invalid input returns 422 invalid_origin_enforcement; unreadable private state returns 503 origin_enforcement_unavailable. After an uncertain commit, reread current state before starting another preview.

Refusals

Every policy write queues in an outbox the tracker must acknowledge; see Security model and trust boundaries for the mechanism. A write that finds a full backlog of 256 unacknowledged entries is refused before it changes anything.

New role and QoS routes use exact strong ETags and return 409 operation_backlog_full for a full outbox. The legacy quarantine route keeps its own refusals, which mean different things:

Full descriptions of every code, including precondition_required, precondition_failed, confirmation_required and role_in_use, are in API error codes (problem types).