Files
pages/docs/design/locality-publication-ownership.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

272 lines
17 KiB
Markdown

# Locality owners and constrained publication
Status (2026-09-14): **owner appointments and publication-policy drafts implemented**.
The subsequent [user/group and anonymous approval slice](locality-access-publication.md)
now enables separately approved current-revision Viewer/media access. It supersedes
the earlier anonymous-disabled status below, not the remaining full dependency/
mutation gates. No saved draft is activated automatically. This supersedes the earlier proposal
that a child publication setting could simply override an ancestor's restriction.
## Implemented first slice
- Stable-UUID Quartier/Spot bindings support up to 32 co-owners. Appointment is
limited to active local Domain memberships; only active principals/memberships
exercise authority. Revocation/suspension is checked on each request.
- `domain_admin` owner/manager membership is authoritative for this API; generic
document write/manage grants, ordinary group administration and an unrelated
`campus_admin` membership are not a fallback. Existing explicitly inherited
Domain authority must materialize through the established group lifecycle.
- Quartier owners govern their own Quartier, Streets and Spots, and appoint
Spot owners only. They cannot appoint peers. Spot owners cannot appoint peers
or mutate topology/content through this feature. Existing content read ACLs
still govern detail pages; the governance API itself exposes configuration,
not Page bodies or an unfiltered Page list.
- Domain policy defaults to `authenticated_acl`; `public` there permits draft
publication but does not publish the root. Local defaults are `inherit`.
The evaluator intersects all caps, separately retaining publication intent.
Saving `public` beneath a restrictive cap fails; superior tightening clamps
previously stored descendant intent without erasing it.
- Relaxations require explicit confirmation. **This is a draft confirmation,
not publication-impact consent**. This endpoint retains `impact_complete:false`;
its `publication_enabled` now reports this node's separate approved manifest.
`GET/PATCH .../publication` provides bounded current-revision review/approval,
excluding aliases and dependencies. Do not silently activate saved drafts.
- `GET` / `PATCH /_/api/v1/city/{zones,spots,domains}/{uuid}/governance` are
handler-authorized with the existing session and CSRF protections. Only the
requesting Domain UUID is accepted for `domains`. Zone kind and active,
same-Domain parentage/strict descendant Paths are verified, not inferred from
client claims. Invalid/missing targets fail closed.
- `POST .../governance/preview` validates a proposed owner/policy draft without
persisting it; it is **not** a Page/alias publication-impact report.
`GET .../governance/members?q=...` is appointment-authorized, returns at most
30 matching active local display identities, and never returns emails/tokens.
- PATCH/preview require both Domain governance `epoch` and `topology_version`.
A write reservation is acquired before reading actor membership, group/owner
authority, parent chain and policies, so a concurrent revocation cannot commit
between authority validation and the write. Stale versions return 409. Preview
rolls back its short reservation; no-op saves currently advance the epoch.
Request work has a two-second context deadline; SQLite busy handling can still
return retryable unavailability. There are no cross-request authority caches.
- Additive tables are `city_owner_bindings`, `locality_publication_policies`,
`city_governance_epochs`, and `city_governance_events`. Audit records contain
actor UUID, node UUID, epoch, timestamps and before/after configuration, not
document bodies or secrets. These are a local transactional audit log, not
the future durable Domain activity outbox or request-ID-correlated audit UI.
- Details have a themed settings-icon dialog with owners, member lookup, local
policy, ancestor caps and draft result. Domain draft ceiling is reachable
from the City Map utility menu's settings icon; configuration-panel embedding
can reuse this component later. Labels, confirmations and errors support
Japanese/English. Opening/closing and stale async responses are guarded.
Not completed: complete dependency/alias impact, impact-aware move/merge/archive/
import/reconciliation (the current ACL guard rejects structural changes), orphan
binding cleanup, anonymous discovery, full audit UI/outbox and automatic future
revision publication. The separate bounded Viewer/media activation and revocation
slice is specified in [the implementation contract](locality-access-publication.md).
Verification: `city_governance_test.go` in Store/Server covers cap intersections,
multiple owners, self/peer appointment denial, unrelated Quartier/Domain denial,
active membership checks, owner/admin revocation, blocked intents, explicit
relaxation, non-persisting preview, stale epochs/topology, concurrent saves and
CSRF. `city_governance_browser_test.go` exercises real dialog/member search/save/
reopen for both locality and Domain controls in Chromium.
## Requirements and boundary
- Quartiers and Spots can have explicitly appointed owners, including multiple
co-owners. Ownership is scoped governance, not a Domain administrator Role.
- A subordinate owner may narrow the publication audience permitted by superior
governance, never enlarge it beyond an ancestor's ceiling.
- Preserve existing authenticated content ACLs. Ownership and publication do not
implicitly grant editing, deleting, membership administration, historical
Revision access, object enumeration or arbitrary code execution.
- Do not disable `authorization_mode=enforcing` to implement public localities.
Anonymous publication must be a separate, explicitly authorized read path.
- Broadening anonymous access must use
[safe HTML projections](html-projection-trust.md), now implemented for normal
displays, and pass the governance/mutation/revocation gates below. OGP itself
grants no read authority.
## Ownership and appointments
Initial bindings refer to active Domain memberships (and their Principal), not
usernames. User renames do not change ownership. Multiple owners are supported;
an ownerless node falls under its superior administrators. Group ownership can
be added later only with an explicit group-membership/delegation policy; ordinary
group managers must not silently acquire publication-administration powers.
| Actor | May appoint/remove owners | May administer publication |
| --- | --- | --- |
| Domain administrator | Quartier and Spot owners in its Domain | Domain ceilings and locality policies |
| Quartier owner | Spot owners within that Quartier | That Quartier, its Streets and Spots, bounded by superior ceilings |
| Spot owner | No appointment or co-owner changes by default | Its own Spot, bounded by all superior ceilings |
| Ordinary Page author / group admin | None by this feature | None by this feature |
Quartier owners do not appoint their own peers or remove superior authority.
Spot owners do not transfer ownership or add co-owners themselves. Superior
appointment keeps delegated authority auditable and avoids accidental transfer
of publication control. Street has no independent owner role in this slice;
its Quartier governs Street policy. A future Street owner must obey the same
attenuation rules, not create a separate bypass.
Campus administrators retain their existing Campus authority and explicit
Domain-admin inheritance semantics. Do not add an unconditional cross-Domain
content/ownership bypass merely because an account belongs to `campus_admin`.
Owner appointments, revocations, account suspension and Domain membership
revocation take effect on the next request. Ownership bindings cannot outlive
their Domain scope or be imported as authority through untrusted topology data.
An owner must also have explicit read access to inspect document content; a
governance UI can report counts without revealing otherwise unreadable bodies.
## Publication ceiling is not a publication grant
There are two independent decisions:
1. **Ceiling:** the widest audience superior governance allows.
2. **Publication intent:** whether this locality and its Path subtree are
actually being published, or inherit an explicit ancestor publication.
A Domain starts with an authenticated-only ceiling and no anonymous publication.
Allowing public publication at the Domain ceiling does not publish the Domain
root, unconfigured localities, or arbitrary Pages. A Quartier/Spot owner must
then explicitly publish a locality, or inherit an already published ancestor.
The first UI supports:
- `inherit`: retain the ancestor publication intent; add no restriction.
- `public`: request anonymous read for this boundary and descendants. Accepted
only when every ancestor ceiling allows it; also establishes public intent
inherited by descendants.
- `authenticated_acl`: block anonymous reads here and below. Authenticated
readers still need the existing read grants; this does **not** grant every
logged-in account access. It acts as a ceiling that descendants cannot widen.
Thus a public Quartier may contain an authenticated-only Spot, but an
authenticated-only Quartier cannot contain a public Spot. An unconfigured
Quartier under a Domain that merely *allows* publication is not public; a Spot
may explicitly be published there only if no ancestor imposed a narrower cap.
Unpublished parent metadata is not thereby published with that Spot.
For anonymous access:
`allowed = explicit-or-inherited publication intent AND every ancestor ceiling`
For authenticated readers, retain the existing ACL evaluator. If selected-group
audience caps are introduced later, they must be an additional intersection,
not a positive grant or a priority-ordered override. Formally, effective audience
is the intersection of all applicable caps and the branch's positive read basis.
Predicates should be combined at evaluation time; do not enumerate users to
compare audiences. This slice does not introduce selected-group restrictions
or change current positive-grant semantics without a separate migration.
An attempted `public` save under an authenticated-only cap fails explicitly;
do not store a misleading, silently clamped UI value. If a superior subsequently
tightens a ceiling, existing descendant public intent becomes ineffective
immediately without deleting the descendant's policy. A later relaxation must
preview and explicitly confirm any previously blocked public intent becoming
effective. Explicit child `authenticated_acl` restrictions remain in force.
Returning a child from `authenticated_acl` to `inherit` can reopen access where
the parent is public. It is permitted within the owner's superior ceiling, but
requires the same public-impact confirmation as choosing `public`. Attenuation
is relative to superior authority, not an irreversible chronological lock.
## Scope and bypass resistance
- Publication follows the literal Path boundary, including its portal and new
descendant Pages. `/life` never matches `/lifestyle`; `%`, `_`, Unicode and
encoded separators are not SQL wildcards or a second decoding opportunity.
- Related Spot/Page appearances, reference edges and bookmarks never convey
publication. A public Page can link to a private Page without exposing its
private title, description, contents or preview.
- City/search/children/OGP/thumbnail projections use the same anonymous read
decision. Suppress unreadable ancestor names in public breadcrumbs; do not
make the ancestor public merely to show a published child.
- Owner and policy bindings are keyed by stable UUID. Changing a boundary,
moving a Street/Spot, recursive rename, link/unlink, import, merge, archive,
deletion and reconciliation all require publication-impact checks. Ordinary
document `write`, `rename` or `link` cannot publish previously private bytes
by moving/aliasing them into a public boundary. New content written directly
into an already public boundary follows its policy; make that visible in UI.
- Do not silently discard restrictions on node deletion, merge or archive.
Preserve equivalent restrictions or require a superior-authorized explicit
policy transition. Reconciliation cannot remove manually imposed restrictions
or create owner bindings.
- Aliases require special attention: if an Object is published through one
allowed Path, those same content bytes are not secret through another alias.
Warn in impact previews and require publication authority; do not expose other
alias names or infer that raw UUID/hash/history endpoints are now public.
- Initially publish only the current safe Viewer and the current approved media
needed by it. Assets, previews and embedded resources get independent checks;
never enumerate or publish historical revisions through a public Page.
## Persistence and remaining target API contract
Separate tables, rather than opaque `zones.policy_json` authorization:
- `city_owner_bindings`: Domain UUID, node kind/UUID, membership UUID, appointing
Principal, timestamps; unique binding per node/member.
- `locality_publication_policies`: Domain UUID, node kind/UUID (including Domain),
intent/cap, policy version, actor and timestamps. Initial enum constraints
disallow arbitrary audience JSON. Ancestor joins validate active, same-Domain
parentage. Governance version is independent of cosmetic layout version.
- Domain publication-policy epoch: changes to ancestors invalidate derived
decisions, summaries and pending impact confirmations.
- Audit/outbox: before/after owners, policies and effective-publication impact,
actor, versions and request ID. No payload bodies or secrets in audit records.
Handler-owned endpoints (configuration operations implemented; full publication
impact reports remain pending):
| Endpoint | Purpose |
| --- | --- |
| `GET /_/api/v1/city/{zones,spots}/{uuid}/governance` | Authorized owners, local policy, superior ceilings and effective result |
| `POST /_/api/v1/city/{zones,spots}/{uuid}/governance/preview` | Owner/policy draft validation only |
| `PATCH /_/api/v1/city/{zones,spots}/{uuid}/governance` | Versioned owner/policy mutation with scoped authority |
| `GET/PATCH .../governance/access` | Named user/group restrictions within superior caps |
| `GET/PATCH .../governance/publication` | Bounded current-revision impact, explicit approval and revocation |
Domain ceiling is Domain-scoped with its own policy epoch; the current UI lives
in the City Map utility menu and can later be embedded in Domain configuration.
The endpoint registry must deliberately admit scoped owners for these operations;
do not relax the existing Domain-admin guard on unrelated City mutations.
Resolve actor membership/ownership, parent chain, caps and expected policy epoch
in one transaction. Stale versions return 409; insufficient authority returns
403 (or 404 for an unreadable target). Fail closed on unknown/malformed policies,
missing parents, foreign references, limits and query errors. Reject exhausted
impact previews rather than treating a truncated list as complete consent.
Use bounded bulk reads / request-scoped snapshots, not a query per Page or a
process-wide authority cache. Public-mode decisions must be part of cache keys;
revocation takes precedence over any immutable-image cache reuse. Third-party
social caches cannot be recalled after publication; disclose this at confirmation.
## UI and implementation sequence
Use a settings-icon modal in Quartier/Spot details, with three compact sections:
owners, publication, and affected Pages. Show the superior ceiling, local choice,
effective status and the source of each inherited restriction. Disable forbidden
choices with explanations, but enforce all rules again server-side. Use existing
locale/theme/dialog conventions; localize both UI and permission errors.
Implementation order:
1. Completed prerequisite: inert HTML projection boundary and browser denial
regressions. No executable compatibility mode or anonymous grant was added.
2. Completed first slice: scoped owner bindings / appointments, versioned policy
storage, pure cap evaluator and governance API/UI. Public enabling and full
Page/alias impact preview remain release-gated.
3. Structural mutation/alias/import/reconciliation fencing and publication audit.
4. Common anonymous read policy under enforcing authorization, safe current
Viewer/media projections, filtered discovery and OGP integration.
5. Revocation/cache tests and staged enablement without changing existing Domains.
Required regressions include co-owners, removed/suspended owners, foreign Domain
IDs, parent appointment rules, peer self-appointment denial, direct API bypass,
ancestor tightening races, unpublished ancestors with a public child, child
reopening within a permitted cap, move/merge/archive/alias bypasses, batch limits,
literal Paths, current-vs-history access, private preview dependencies, inherited
admin revocation, public/private cache isolation, and preserved canonical bytes.