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.
272 lines
17 KiB
Markdown
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.
|