Secret authorization
Development preview
This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.
This document owns the policy for deciding which repository secrets a CI job may use. SecretBroker separates the public authorization decision from secret-value retrieval so the decision can be audited without exposing names or values.
Authorization rule
The trigger author, secret owner, and acting maintainer must all be in one recursive maintainership excluding invited maintainers. A tagged trigger must also sign at least one repository reference which is either a current member coordinate in that view or the selected coordinate which safely forwards to it.
Exactly one selected coordinate is chosen for each decision:
- Under
request-required, the broker first restricts Service Requests to repository references which resolve the trigger's maintainership excluding invited maintainers, then selects the newest accepted, unstopped Request. Its signed repositoryareference is the selected coordinate; its author is only the requester. - Under
automatic, the broker chooses the first matching configured whitelist reference in stable repository-coordinate order.
The selected coordinate resolves exactly one current authority seed. A valid active M path terminates at the acting maintainer; otherwise a current legacy or leadless selected author is the acting maintainer. The broker never combines evidence from separate views. The trigger author, acting maintainer, and every released secret owner need current kind-30617 announcements and confirmed membership. The selected coordinate may instead belong to a former maintainer retaining a redirect: that signer and its secrets remain excluded. An invitation, inbound-only maintainer claim, incomplete valid lead path, or cycle containing only unconfirmed invitees is not enough for secret access, although the workflow may still run without secrets. A malformed M entry is ignored rather than treated as a pointer.
Repository state events have no signed repository reference, so their author, secret owner, and acting maintainer must share the maintainership. When a manual request quotes a PR, the signed repository references come from that PR, not from the manual request. Mixed-identifier trigger references receive no secrets.
Release triggers validate the kind-30063 release, the same-publisher kind-32267 application and its signed repository references, and exact asset metadata before entering this decision sequence. The publisher must be a current confirmed maintainer of the linked watched repository. A repository link from an unrelated publisher is not authority. Restarting a release also requires the usual manual-request authority and retains the original release snapshot.
Regression coverage: release_links_require_confirmed_publishers_and_preserve_secret_policy checks multiple applications, unrelated repositories/publishers, direct broker rejection and standing request gating. The relay-backed release_publication_pins_source_recovers_assets_freezes_replacements_and_retries checks scoped secret delivery on a valid release and its explicit restart.
Issue activities execute the pinned default-branch source, but opening or closing an issue does not grant repository secret authority. The existing confirmed-maintainer rule applies to the activity signer. A maintainer's status change may authorize secrets for that repository; an external author's status change may not. The root's signed repository references must agree with the selected repository.
Regression coverage: issue_nix_workflows_pin_source_scope_secrets_and_retain_restart_context checks denial for an external issue author, scoped secret delivery for a maintainer status, exact source checkout, and retained context on an authorized restart.
Decision sequence
SecretBrokerverifies the trigger signature, kind, and normalized signed fields, then extracts the author, one identifier, and any effective signed repository references.- The private secret store returns only the value-free repository references against which applicable secrets are held. If there are none, no graph query is needed.
- The watcher returns possible selected coordinates: configured whitelist references under
automatic, or signed repository references from observed Service Requests and Stops underrequest-required. MaintainerGraphqueries rust-nostr's persistent event database once for the identifier and rebuilds one confirmed view for each selected-coordinate candidate. Views with equal member sets remain separate. It returns only in-memory membership, selected-coordinate, authority-seed, and relay facts; it does not know which references are acting or hold secrets and does not use the watcher's in-memory graph for this decision.SecretBrokerevaluates each selected-coordinate view independently. It keeps only views containing the trigger author. A signed current-member reference binds every view containing that member, while a forwarding reference binds only the exact selected coordinate it names. It then asks the watcher to select exactly one coordinate across those matching views according to current Service Request/Stop policy.- The broker maps that selected coordinate to its current authority seed and verifies that the seed is a confirmed maintainer. Only then does it retain secret owners in that exact maintainership. If none qualify, the decision is denied; it never falls back to an older Request or another configured root merely because that view has secrets. Every membership check uses the in-memory result and never repeats the persistent cache query.
- The broker requires at least one relay announced by that maintainership to be connected and to have completed repository control-history EOSE since its latest connection. One ready relay from that confirmed view is sufficient. Failure to establish this confidence withholds that secret scope but does not prevent the workflow from running.
- The broker returns a value-free authorization. Only
authorize_and_retrieveuses it immediately to retrieve and merge the corresponding values.
Relationship denial and unavailable relay confidence are different outcomes. The current broker withholds immediately in both cases, but it performs relay checks only after a scope passes the confirmed-maintainership rule and logs that distinction. No connection wait is currently part of authorization. Any future retry policy must re-run acting state and maintainership authorization; unauthorized triggers and jobs with no applicable secret scope must never wait.
Authorization scenarios and regression coverage
These cases define the focused unit and relay-backed integration coverage for this policy. The Coverage column points to exact tests in the regression index below. Broader integration tests supplement rather than replace these named checks.
The formulas use these symbols:
| Symbol | Meaning |
|---|---|
A | The trigger author's pubkey paired with the decision's repository identifier. |
S | The one configured or Request-signed coordinate selected for this decision. |
P(S) | The current maintainer authority seed safely resolved from S. |
R | A repository reference against which secrets are held. A bare-pubkey scope is paired with the decision's identifier. |
T | An effective signed repository a reference from a PR or Manual Trigger. |
L(X) | Same-identifier repository references in X's direct current maintainer listing. |
E(S) | Recursive maintainership excluding invited maintainers, selected through S and seeded at P(S). |
P(S) follows exactly one valid active M at each step until an active self-M terminates the path. With no active M, S.pubkey is the legacy or leadless seed unless its own role is ended. A missing, conflicting, or cyclic explicit path defines no seed. E(S) is the reciprocal least fixpoint from that seed: each new member must be listed by a confirmed member, have a current announcement, assign a valid active M or m role to an already-confirmed member, and not have ended their own maintainer role:
text
E0(S) = { P(S) } when P(S) resolves; otherwise E0(S) = ∅
E(n+1)(S) = E(n)(S) ∪ {
X | ∃ Y,Z ∈ E(n)(S): X ∈ L(Y) ∧ Z ∈ L(X) ∧ X has not left
}
E(S) = ⋃n E(n)(S)An announcement's listing is the set of active entries in its indexed NIP-34 M/m role tags, or its deprecated maintainers tag when no role tag (M, m, or o) is present. Moderator (o) entries are never part of the listing. Any pubkey whose own role tags name them without an active M/m entry has left the maintainership and is excluded from E(S) even while other announcements still assign them a role. This includes S.pubkey: an active redirect can resolve P(S) without making the forwarding signer a member.
request(P2) > request(P1) uses the Service Control protocol's total order: a later created_at wins, and at equal timestamps the lexicographically lower event ID is later.
| Scenario | Formula | Plain relationship | Expected | Coverage |
|---|---|---|---|---|
| Direct tagged authorization | A, P(S), R ∈ E(S); T ∈ E(S) or T=S; and R=P(S) | The acting maintainer owns the secret scope; the author and signed trigger reference select its confirmed maintainership. | Release R. | I1 |
| Forwarding selected coordinate | S.pubkey ∉ E(S); A, P(S), R ∈ E(S); T=S | A former maintainer's signed M routes to the current lead without restoring the former signer or its secrets. | Release qualifying R; never release a scope owned by S.pubkey. | G7, I2, I4 |
| Equivalent forwarding views | E(S1)=E(S2); T=S2; T∉E(S1) | Equal member sets remain separate selected-coordinate views, and the signed former coordinate names only one forwarding entry point. | Keep S2 eligible; do not select S1 through T=S2. | G5, I3 |
| Recursive confirmed maintainership | A, P(S), R ∈ E(S) and R≠P(S) | Each non-seed perspective was listed and acknowledged through the incremental confirmed-member fixpoint. | Release R. | G3 |
| Newest matching Request | S=S2; request(S2) > request(S1); A ∈ E(S1) and A ∈ E(S2) | Two accepted, unstopped Requests match the trigger maintainership. | Select S2. | S1, I6 |
| Newest matching Request has no secret owner | request(S2) > request(S1); A,R ∈ E(S1); A ∈ E(S2); R ∉ E(S2) | The newer Request matches the trigger but its view contains no applicable secret owner. | Select S2 and deny secrets; never fall back to S1. | I6 |
| Newer unrelated Request | A ∈ E(S1); A ∉ E(S2); request(S2) > request(S1) | A newer Request belongs to another confirmed maintainership. | Ignore S2; select S1. | W1 |
| Request author differs from selection | request(S) is signed by an accepted requester other than S.pubkey | Request authorization and coordinate selection are separate. | Select the Request's signed a reference S, never its author. | I4 |
| Automatic deterministic selection | A ∈ E(S1) and A ∈ E(S2); coordinate(S1) < coordinate(S2) | Multiple configured references match under automatic policy. | Select S1. | W1 |
| Invited but unconfirmed author | ∃ Y ∈ E(S): A ∈ L(Y); L(A) ∩ E(S) = ∅ | A confirmed member lists the author, but the author's announcement acknowledges no already-confirmed member. | Deny. | G1, I1, I9 |
| Inbound maintainer claim | P(S) ∈ L(A), A ∉ E(S) | The author lists or claims the acting maintainer without being recognized by the selected view. | Deny. | G4, I1 |
| Unconfirmed secret owner | ∃ Y ∈ E(S): R ∈ L(Y); L(R) ∩ E(S) = ∅ | A confirmed member lists the secret owner, but the secret owner's announcement acknowledges no already-confirmed member. | Deny R. | I1 |
| Circular invitation | B ∈ L(P(S)); C ∈ L(B); P(S) ∈ L(C); no other cross-member assignments | Two invitees form a path back to the acting maintainer without either acknowledging an already-confirmed member at its confirmation step. | E(S)={P(S)}; deny B and C. | G2, I5 |
| Cross-maintainership splice | A,T ∈ E(S1); R ∉ E(S1); R ∈ E(S2); A ∉ E(S2) or every T ∉ E(S2) | One selected view authorizes the trigger while another contains the secret owner; no single view contains every participant. | Deny R. | I7 |
| Unbound signed reference | A, R ∈ E(S); every T ∉ E(S) and T≠S | The author and secret owner are confirmed, but none of the signed trigger references belongs to or selects their maintainership. | Deny tagged trigger. | I1 |
| Multiple references, one bound | T1 ∈ E(S) or T1=S; T2 ∉ E(S) and T2≠S | One same-identifier signed reference selects the confirmed maintainership and another does not. | T1 permits evaluation; T2 adds no authority. | I1 |
| Mixed identifiers | identifier(T1) ≠ identifier(T2) | One signed trigger attempts to span two repository identifiers. | Deny all secrets before graph evaluation. | I1 |
| State event | No T; A, P(S), R ∈ E(S) | The state-event author and secret owner share the acting maintainer's confirmed maintainership. | Release R. | I1 |
| Manual request quoting a PR | T = quoted PR references | The manual request's own repository tags disagree with the quoted PR; only the quoted PR's signed references define scope. | Request tags add no authority. | I7 |
| Fresh revocation | Any required E(S) membership or the resolution of P(S) is broken | A replacement or deletion breaks authority for the acting maintainer, author, or secret owner. | Withhold immediately on the next decision. | G3, I1, I8, I10 |
| Matching maintainer Stop | stop(E(S)) > request(S) | A current maintainer's newer Stop closes every earlier Request in the same confirmed maintainership. | Produce no S; withhold secrets and ordinary execution. | S2, I1, I11 |
| Later Request reopens | request(S) > stop(E(S)) | A newer accepted Request follows the Stop. | Select S again. | S2, I1, I11 |
| Unrelated Stop | stop(S2), P(S2) ∉ E(S) | A Stop belongs to another maintainership. | Do not close S's Request. | S4 |
| Requester-local Stop | stop(Aq) > request(Aq,S) and Aq is an accepted non-maintainer requester | The requester can close their own earlier Requests but cannot stop the whole maintainership. | Ignore only Aq's earlier Requests. | S3 |
| No selected coordinate | Policy produces no S | Candidates may exist, but every matching Request is stopped, unaccepted, or lacks repository control-history readiness. | Deny before relay-connectivity confidence. | I1 |
| Manual request without standing Request | request-required and policy produces no S | A valid one-shot Manual Trigger does not itself start standing service. | Run according to ordinary manual admission, but release no secrets. | I1 |
| Unannounced selected candidate | no current 30617 for candidate S | Acting state references a perspective which cannot establish current maintainership. | Deny. | G6 |
| Repository control history unavailable | no confirmed-member relay has completed the control subscription for S | Cached relationships exist, but current acting state is not ready. | Produce no S; deny before relay-connectivity confidence. | I12 |
| No applicable secret owner | every configured R ∉ E(S) | Trigger and acting selection qualify, but no held secret belongs to their maintainership. | Deny without a relay-connectivity check. | I6 |
| Disconnected maintainership | A, P(S), R ∈ E(S); no confirmed-maintainership relay is connected and freshly EOSE-synced | Cached relationships authorize the use, but their freshness cannot be established with the required confidence. A reconnect clears the previous EOSE marker. | Log confidence unavailable and withhold immediately. | I1 |
| Multiple qualifying secret scopes | A, P(S), R1, R2 ∈ E(S) | Both secret owners belong to the same confirmed maintainership. | Merge both scopes. | I1 |
| Wildcard secret scope | R=(configured pubkey, trigger identifier) and R ∈ E(S) | A bare-pubkey alias becomes a concrete reference for this identifier and must be confirmed like any other secret owner. | Release only for the qualifying identifier. | I7 |
Regression index
Graph tests live in src/maintainer_graph.rs, watcher and service-control unit tests in their matching src/ files, and relay-backed broker tests in tests/watcher_subscriptions.rs.
| ID | Exact test function |
|---|---|
| G1 | confirmed_membership_omits_one_way_relationships |
| G2 | circular_invitees_do_not_confirm_each_other |
| G3 | every_confirmed_view_read_uses_the_latest_persistent_graph |
| G4 | inbound_maintainer_claim_does_not_join_selected_view |
| G5 | confirmed_views_preserve_selected_coordinates_and_authorities |
| G6 | unannounced_selected_coordinate_has_no_confirmed_view |
| G7 | former_selected_maintainer_routes_to_lead_without_gaining_authority |
| W1 | selected_coordinate_uses_policy_after_trigger_group_matching |
| S1 | selects_newest_accepted_unstopped_request |
| S2 | maintainer_stop_closes_all_earlier_requests_and_later_request_reopens |
| S3 | requester_stop_closes_only_their_own_earlier_requests |
| S4 | outsider_stop_cannot_close_another_authors_request |
| I1 | secret_broker_validates_triggers_and_reloads_connected_graph |
| I2 | forwarding_coordinate_uses_current_lead_for_ci_and_secret_authority |
| I3 | signed_forwarding_reference_selects_only_its_exact_view |
| I4 | request_required_multi_hop_forwarding_releases_only_current_member_secrets |
| I5 | broker_withholds_owner_secret_from_circular_invitees |
| I6 | broker_does_not_fallback_from_newer_matching_request_without_secrets |
| I7 | broker_keeps_wildcard_and_manual_pr_secrets_in_one_confirmed_maintainership |
| I8 | nip09_announcement_deletions_revoke_cached_execution_and_secrets |
| I9 | one_way_invited_maintainer_state_neither_triggers_nor_changes_baseline |
| I10 | state_handover_ignores_former_maintainer_before_and_after_restart |
| I11 | request_and_stop_move_a_configured_repository_in_and_out_of_acting_status |
| I12 | inbox_request_does_not_act_before_a_repository_relay_completes_sync |
The role parser and authority routing also have focused graph tests for role-tag precedence, ended and malformed histories, moderator-only announcements, ended self-roles, missing/conflicting/cyclic lead paths, and cache-backed M/m/o behavior. Their test names state the rejected edge case directly.
Malformed signatures, altered commits or workflow hashes, normalized coordinates absent from the effective signed references, missing current announcements, invitation cycles without an acknowledgement to an already-confirmed member, and invalid maintainer entries are additional fail-closed validation cases. Out-of-spec duplicate role-tag entries for one pubkey are consolidated rather than rejected: since only current activity is ever evaluated, the pubkey is listed while any entry is active.
Nix pull-request jobs
Ordinary Nix PR jobs cannot request repository secrets, including when the PR author is a confirmed maintainer. They use hardware VMs by default. The explicit weak-container tier also permits PR execution for an authorized repository/head-revision signer pair; it does not relax this PR secret restriction. The coordinator rejects a declaration before secret retrieval or provider allocation; providers independently reject PR allocations containing a secret grant. Secret-free run jobs may publish previews with a disposable identity created inside the disposable job environment. Maintainer-authorized manual runs retain the existing secret authorization checks. This restriction is specific to Nix; it does not change the act authorization scenarios above.
Nix provider permission
Repository authorization and compute-provider permission are separate checks. A Nix job with declared secrets selects only an explicitly secret-authorized provider before retrieval or decryption. Retry selection uses the same class; recovery never republishes a grant to a now-disallowed provider, while retaining result recovery for allocations that might already be running. See provider trust configuration. The catalog selection regression covers disjoint/overlapping grants and safe reassignment; recovery_collects_result_without_republishing_after_trust_revocation covers durable allocation recovery after permission removal.
Value handling boundary
Secret values are accepted from environment/.env, systemd credentials, or authenticated Repository Secret Updates reduced into separate encrypted local state; they are never accepted on argv or stored in the general Nostr event cache. SecretBroker owns the private runtime view, and callers cannot resolve it directly. Authorization objects contain repository references and event principals, never secret names or values.
Values are retrieved only after authorization. Native jobs receive their declared values through encrypted provider grants and job-private files; see secret-bearing work. The retained act backend passes values through its environment; only names appear in the act invocation. Operator-provisioned and Nostr values are merged; for a same-name collision the operator value wins. Within operator inputs, exact-coordinate secrets override a wildcard secret with the same name for that concrete repository. See configuration for provisioning and precedence.