From cbe48d9ce2a040dbc8f84bb05894caa0543d631e Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Thu, 20 Aug 2026 19:14:49 +0000 Subject: [PATCH] docs: define owner-view PR ref authority Motivation: The authorization-integrity implementation now recognizes exact standard clone endpoints as an alternative owner-view authority, but the v3 changelog and migration architecture still described only maintainer-overlap propagation. Approach: Document both accepted owner-view paths and explicitly state that foreign services, different coordinates, URL suffixes, and /prs/ endpoints do not satisfy the standard endpoint rule. Preserve the existing GRASP-06 warning and operator requirement to inspect manual findings. Correctness assumptions: The accepted event database remains authoritative and GRASP-06 contributor views continue to use their separate signer plus exact /prs/ coordinate predicate. Excluded scope: This changes no runtime behavior, deployment pin, release tag, or production repository data. Validation: git diff --check; review against the remotely built and production-validated 44a16da9 behavior. --- CHANGELOG.md | 5 ++++- docs/explanation/architecture.md | 11 +++++++---- docs/explanation/git-family-object-storage.md | 13 ++++++++----- docs/how-to/upgrade-git-family-storage.md | 7 +++++-- 4 files changed, 24 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fdbd896..27cf8a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -88,7 +88,10 @@ Expect a bit of downtime as a git data migraiton is performed on startup. The la non-blocking authorization-integrity pass that compares every served branch, tag, `HEAD`, and `refs/nostr/*` ref with the accepted State, PR, and PR Update events (including precisely scoped - in-flight events). It repairs unambiguous differences and emits + in-flight events). Owner-view PR refs require either confirmed-maintainer + overlap with the target or an exact standard clone URL naming that owner and + identifier on the service; similar, foreign, and `/prs/` URLs do not count. + It repairs unambiguous differences and emits `manual_inspection=true` errors without deleting unexplained PR refs that may be evidence. GRASP-06 operators must check those logs and the terminal `Git authorization-integrity startup pass completed` summary; any non-zero diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index 7569fef..e227f79 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -93,10 +93,13 @@ runtime: - Start non-blocking storage-integrity and authorization-integrity passes after database initialization. The former checks family objects and thin-view wiring; the latter reconciles each served ref against accepted State, PR, - and PR Update events, auto-repairing only unambiguous differences and - logging preserved evidence for manual inspection. Both cover all families - by default, with a shared temporary identifier scope for staged validation; - durable manual requests run the same pair in check-only or repair mode + and PR Update events. Owner-view PR refs require confirmed-maintainer overlap + or an exact service-local standard clone coordinate; GRASP-06 views retain + their stricter signer and `/prs/` coordinate checks. The pass auto-repairs + only unambiguous differences and logs preserved evidence for manual + inspection. Both cover all families by default, with a shared temporary + identifier scope for staged validation; durable manual requests run the same + pair in check-only or repair mode - Serve HTTP + WebSocket until a caller-supplied shutdown future resolves, then stop background mutation, persist a final state snapshot (purgatory and rejected-events cache), and clean up placeholder refs diff --git a/docs/explanation/git-family-object-storage.md b/docs/explanation/git-family-object-storage.md index 8786dd8..94166c5 100644 --- a/docs/explanation/git-family-object-storage.md +++ b/docs/explanation/git-family-object-storage.md @@ -405,11 +405,14 @@ on remote servers. Authorization integrity is the second, view-scoped layer. It derives each owner's branch, tag, and `HEAD` set from the NIP-01-preferred accepted State event published by that owner's confirmed maintainer set. It derives -`refs/nostr/` from accepted PR and PR Update events using the same -maintainer-overlap propagation rule as normal event processing. GRASP-06 views -also require the signer and this relay's clone URL to name that exact -submitter/identifier coordinate. Exactly scoped active purgatory entries are -recognized so an in-flight push is not mistaken for corruption. +`refs/nostr/` from accepted PR and PR Update events when the same +confirmed-maintainer overlap as normal event processing selects the view, or +when an exact standard clone URL names that owner and identifier on this +service. Foreign hosts, different coordinates, URL suffixes, and `/prs/` URLs +cannot authorize a standard owner view. GRASP-06 views separately require the +signer and this relay's clone URL to name that exact submitter/identifier +coordinate. Exactly scoped active purgatory entries are recognized so an +in-flight push is not mistaken for corruption. The pass creates or updates missing/wrong authorized refs once their objects are available, deletes stale State-governed branch and tag refs, and repairs diff --git a/docs/how-to/upgrade-git-family-storage.md b/docs/how-to/upgrade-git-family-storage.md index bb35304..00bb5ef 100644 --- a/docs/how-to/upgrade-git-family-storage.md +++ b/docs/how-to/upgrade-git-family-storage.md @@ -96,8 +96,11 @@ The authorization pass treats the accepted event database as authoritative: - the latest State event from the owner's confirmed maintainer set defines all and only `refs/heads/*`, `refs/tags/*`, and `HEAD`; -- accepted PR and PR Update events define `refs/nostr/` in every - owner view selected by the existing maintainer-overlap rules; +- accepted PR and PR Update events define `refs/nostr/` in an owner + view when either the confirmed-maintainer overlap selects that view or an + exact standard clone URL names that owner and identifier on this service; + foreign hosts, different coordinates, suffixes, and `/prs/` URLs do not + authorize the owner view; - a GRASP-06 contributor view additionally requires the event signer, clone URL, and repository identifier to match that exact `/prs/` coordinate; - precisely scoped active purgatory entries are tolerated as in-flight state.