Skip to content

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 repository a reference 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 ​

  1. SecretBroker verifies the trigger signature, kind, and normalized signed fields, then extracts the author, one identifier, and any effective signed repository references.
  2. 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.
  3. The watcher returns possible selected coordinates: configured whitelist references under automatic, or signed repository references from observed Service Requests and Stops under request-required.
  4. MaintainerGraph queries 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.
  5. SecretBroker evaluates 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.
  6. 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.
  7. 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.
  8. The broker returns a value-free authorization. Only authorize_and_retrieve uses 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:

SymbolMeaning
AThe trigger author's pubkey paired with the decision's repository identifier.
SThe one configured or Request-signed coordinate selected for this decision.
P(S)The current maintainer authority seed safely resolved from S.
RA repository reference against which secrets are held. A bare-pubkey scope is paired with the decision's identifier.
TAn 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.

ScenarioFormulaPlain relationshipExpectedCoverage
Direct tagged authorizationA, 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 coordinateS.pubkey ∉ E(S); A, P(S), R ∈ E(S); T=SA 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 viewsE(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 maintainershipA, 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 RequestS=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 ownerrequest(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 RequestA ∈ 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 selectionrequest(S) is signed by an accepted requester other than S.pubkeyRequest authorization and coordinate selection are separate.Select the Request's signed a reference S, never its author.I4
Automatic deterministic selectionA ∈ 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 claimP(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 invitationB ∈ L(P(S)); C ∈ L(B); P(S) ∈ L(C); no other cross-member assignmentsTwo 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 spliceA,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 referenceA, R ∈ E(S); every T ∉ E(S) and T≠SThe 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 boundT1 ∈ E(S) or T1=S; T2 ∉ E(S) and T2≠SOne same-identifier signed reference selects the confirmed maintainership and another does not.T1 permits evaluation; T2 adds no authority.I1
Mixed identifiersidentifier(T1) ≠ identifier(T2)One signed trigger attempts to span two repository identifiers.Deny all secrets before graph evaluation.I1
State eventNo 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 PRT = quoted PR referencesThe 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 revocationAny required E(S) membership or the resolution of P(S) is brokenA 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 Stopstop(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 reopensrequest(S) > stop(E(S))A newer accepted Request follows the Stop.Select S again.S2, I1, I11
Unrelated Stopstop(S2), P(S2) ∉ E(S)A Stop belongs to another maintainership.Do not close S's Request.S4
Requester-local Stopstop(Aq) > request(Aq,S) and Aq is an accepted non-maintainer requesterThe requester can close their own earlier Requests but cannot stop the whole maintainership.Ignore only Aq's earlier Requests.S3
No selected coordinatePolicy produces no SCandidates 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 Requestrequest-required and policy produces no SA valid one-shot Manual Trigger does not itself start standing service.Run according to ordinary manual admission, but release no secrets.I1
Unannounced selected candidateno current 30617 for candidate SActing state references a perspective which cannot establish current maintainership.Deny.G6
Repository control history unavailableno confirmed-member relay has completed the control subscription for SCached relationships exist, but current acting state is not ready.Produce no S; deny before relay-connectivity confidence.I12
No applicable secret ownerevery 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 maintainershipA, P(S), R ∈ E(S); no confirmed-maintainership relay is connected and freshly EOSE-syncedCached 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 scopesA, P(S), R1, R2 ∈ E(S)Both secret owners belong to the same confirmed maintainership.Merge both scopes.I1
Wildcard secret scopeR=(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.

IDExact test function
G1confirmed_membership_omits_one_way_relationships
G2circular_invitees_do_not_confirm_each_other
G3every_confirmed_view_read_uses_the_latest_persistent_graph
G4inbound_maintainer_claim_does_not_join_selected_view
G5confirmed_views_preserve_selected_coordinates_and_authorities
G6unannounced_selected_coordinate_has_no_confirmed_view
G7former_selected_maintainer_routes_to_lead_without_gaining_authority
W1selected_coordinate_uses_policy_after_trigger_group_matching
S1selects_newest_accepted_unstopped_request
S2maintainer_stop_closes_all_earlier_requests_and_later_request_reopens
S3requester_stop_closes_only_their_own_earlier_requests
S4outsider_stop_cannot_close_another_authors_request
I1secret_broker_validates_triggers_and_reloads_connected_graph
I2forwarding_coordinate_uses_current_lead_for_ci_and_secret_authority
I3signed_forwarding_reference_selects_only_its_exact_view
I4request_required_multi_hop_forwarding_releases_only_current_member_secrets
I5broker_withholds_owner_secret_from_circular_invitees
I6broker_does_not_fallback_from_newer_matching_request_without_secrets
I7broker_keeps_wildcard_and_manual_pr_secrets_in_one_confirmed_maintainership
I8nip09_announcement_deletions_revoke_cached_execution_and_secrets
I9one_way_invited_maintainer_state_neither_triggers_nor_changes_baseline
I10state_handover_ignores_former_maintainer_before_and_after_restart
I11request_and_stop_move_a_configured_repository_in_and_out_of_acting_status
I12inbox_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.