9 Commits
Author SHA1 Message Date
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
Anya Tokugawa 288e6e94ac Localize config page labels 2026-07-05 00:06:33 +09:00
Anya Tokugawa b37427535c Add district settings management 2026-07-05 00:01:24 +09:00
Anya Tokugawa 8a2ac56844 rename space to district 2026-07-04 23:19:18 +09:00
Anya Tokugawa 94d56f9a8f impl. Kroki, compile path, and code-editor feature 2026-06-18 00:06:16 +09:00
Anya Tokugawa c1bc8f0c03 add theme: Terminal Green, Amber CRT, Lain dark, Nanoha dark 2026-06-01 00:36:15 +09:00
Anya Tokugawa 97970cf105 fix tree view css 2026-06-01 00:27:32 +09:00
Anya Tokugawa 5a596985e0 Add Timezone, Zombie GC. Improved and select theme. 2026-06-01 00:13:30 +09:00
Anya Tokugawa ea3eba180b Improved breadcrumbs list 2026-05-31 23:39:12 +09:00
712 changed files with 150297 additions and 2824 deletions

No files matched your search

+18
View File
@@ -0,0 +1,18 @@
.git
.agents
.codex
.deployment-backups
data
data2
assets/editor/node_modules
assets/city-generator/node_modules
assets/excalidraw-viewer/node_modules
assets/excalidraw-viewer/dist
assets/vimwasm/node_modules
pageswiki
*.db
*.token
.env
.env.*
user.txt
adapter-gateway
+3
View File
@@ -0,0 +1,3 @@
# Copy to .env and set the controller-issued enrollment token for app2.
# .env is local-only and must not be committed.
PAGESWIKI_EXTERNAL_CAMPUS_TOKEN=
+21 -1
View File
@@ -1,3 +1,23 @@
data/
data/*
!data/pageswiki-cli
!data/test_cli_assets.py
!data/pageswiki_cli_test.py
/data2/
/.codex/
/.agents/
/.env
/.env.*
!/.env.example
/user.txt
/pageswiki
/adapter-gateway
**/node_modules/
**/__pycache__/
*.pyc
.tmp/
.deployment-backups/
*.sh
assets/editor/node_modules/
assets/city-generator/node_modules/
assets/excalidraw-viewer/node_modules/
assets/excalidraw-viewer/dist/
+3 -2
View File
@@ -1,8 +1,9 @@
FROM golang:1.22-alpine
FROM golang:1.25-alpine
WORKDIR /src
RUN apk add git
RUN apk add --no-cache ca-certificates git ffmpeg poppler-utils 7zip xz
COPY go.mod go.sum ./
RUN go mod download
+20
View File
@@ -0,0 +1,20 @@
FROM golang:1.25-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /adapter-gateway ./cmd/adapter-gateway
FROM node:22-alpine AS vimwasm
WORKDIR /build
COPY assets/vimwasm/package.json assets/vimwasm/package-lock.json ./
RUN npm ci --omit=dev
COPY assets/vimwasm/app ./app
RUN mkdir -p /out/vendor && cp app/* /out/ && cp node_modules/vim-wasm/vimwasm.js node_modules/vim-wasm/vim.js node_modules/vim-wasm/vim.wasm node_modules/vim-wasm/vim.data /out/vendor/
FROM alpine:3.22
COPY --from=build /adapter-gateway /adapter-gateway
COPY --from=vimwasm /out /vimwasm
COPY static/fonts/hack/HackNerdFont-Regular.ttf static/fonts/hack/LICENSE.md /vimwasm/
EXPOSE 3000
CMD ["/adapter-gateway"]
+11
View File
@@ -0,0 +1,11 @@
FROM node:22-alpine AS build
WORKDIR /src
COPY assets/excalidraw-viewer/package.json ./
COPY assets/excalidraw-viewer/package-lock.json ./
RUN npm ci
COPY assets/excalidraw-viewer/ ./
RUN npm run build
FROM nginx:1.29-alpine
COPY assets/excalidraw-viewer/nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /src/dist /usr/share/nginx/html
+73
View File
@@ -1,3 +1,76 @@
# pageswiki
Simplest and powerful wiki architecture for personal
## Knowledge City Model
Pages Wiki uses urban language for its content hierarchy:
```text
Campus → Domain → Zone (Quartier / Street) → Spot → Page
```
- **Campus** manages a group of Domains.
- **Domain** is a site space selected by a host or subdomain.
- **Zone** is the managed tree containing Quartiers and Streets.
- **Quartier** is a planned aggregation of Streets.
- **Street** groups Spots as the smallest city block.
- **Spot** is the smallest knowledge group.
- **Page** is the smallest knowledge unit and is identified by UUID, not path.
A Page may be linked from multiple Spots. Semantic paths are projections and
must not be treated as Page identity.
## Data CLI
The CLI in `data/pageswiki-cli` provides rsync-like transfers and an
interactive Semantic Path shell over SQLite and `data/documents/`:
```bash
data/pageswiki-cli put article.html path:/quartier/street/spot/page
data/pageswiki-cli get path:/quartier/street/spot/page article.html
data/pageswiki-cli shell
PAGESWIKI_DOMAIN=engineering data/pageswiki-cli ls /
```
The shell supports `ls`, `cd`, `cat`, `view`, `edit`, transfer, Revision,
diff/restore, and link commands, with tab completion and persistent history.
`view` uses `PAGER`; `edit` uses `EDITOR`.
Set `PAGESWIKI_DATA_DIR` when inspecting a different data directory.
`PAGESWIKI_DOMAIN` selects the active Domain by name, UUID, or host. In the
interactive shell, `domain [NAME|UUID|HOST]` displays or changes it.
An instance can enroll into a Controller Campus during container startup:
The included Docker Compose configuration enrolls `app2` into a Controller
Campus. Copy `.env.example` to `.env` and set
`PAGESWIKI_EXTERNAL_CAMPUS_TOKEN` to the controller-issued enrollment token
before running Compose. The token is intentionally not committed; `.env` is
excluded from Git and Docker build contexts. Keep it private (for example,
`chmod 600 .env`).
```bash
PAGESWIKI_INSTANCE_FQDN=node.example.test \
pageswiki --add-external-campus campus.example.test "$CAMPUS_TOKEN"
```
For an explicitly trusted development network without TLS:
```bash
PAGESWIKI_INSTANCE_FQDN=node.internal.test \
pageswiki --add-external-campus-http campus.internal.test "$CAMPUS_TOKEN"
```
For a node dedicated to externally managed Domains, add
`--no-default-campus`. Its bootstrap Campus and Domain remain while approval
is pending, then are removed after the first assigned Domain is pulled:
```bash
PAGESWIKI_INSTANCE_FQDN=node.internal.test \
pageswiki --no-default-campus \
--add-external-campus-http campus.internal.test "$CAMPUS_TOKEN"
```
The controller records the instance public-key fingerprint. Domain placement
only offers instances whose fingerprint has been approved.
+506
View File
@@ -0,0 +1,506 @@
{
"name": "pageswiki-city-generator",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "pageswiki-city-generator",
"dependencies": {
"gen-city": "1.4.6"
},
"devDependencies": {
"esbuild": "0.25.8"
}
},
"node_modules/@esbuild/aix-ppc64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.8.tgz",
"integrity": "sha512-urAvrUedIqEiFR3FYSLTWQgLu5tb+m0qZw0NBEasUeo6wuqatkMDaRT+1uABiGXEu5vqgPd7FGE1BhsAIy9QVA==",
"cpu": [
"ppc64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"aix"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.8.tgz",
"integrity": "sha512-RONsAvGCz5oWyePVnLdZY/HHwA++nxYWIX1atInlaW6SEkwq6XkP3+cb825EUcRs5Vss/lGh/2YxAb5xqc07Uw==",
"cpu": [
"arm"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.8.tgz",
"integrity": "sha512-OD3p7LYzWpLhZEyATcTSJ67qB5D+20vbtr6vHlHWSQYhKtzUYrETuWThmzFpZtFsBIxRvhO07+UgVA9m0i/O1w==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.8.tgz",
"integrity": "sha512-yJAVPklM5+4+9dTeKwHOaA+LQkmrKFX96BM0A/2zQrbS6ENCmxc4OVoBs5dPkCCak2roAD+jKCdnmOqKszPkjA==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.8.tgz",
"integrity": "sha512-Jw0mxgIaYX6R8ODrdkLLPwBqHTtYHJSmzzd+QeytSugzQ0Vg4c5rDky5VgkoowbZQahCbsv1rT1KW72MPIkevw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.8.tgz",
"integrity": "sha512-Vh2gLxxHnuoQ+GjPNvDSDRpoBCUzY4Pu0kBqMBDlK4fuWbKgGtmDIeEC081xi26PPjn+1tct+Bh8FjyLlw1Zlg==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.8.tgz",
"integrity": "sha512-YPJ7hDQ9DnNe5vxOm6jaie9QsTwcKedPvizTVlqWG9GBSq+BuyWEDazlGaDTC5NGU4QJd666V0yqCBL2oWKPfA==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.8.tgz",
"integrity": "sha512-MmaEXxQRdXNFsRN/KcIimLnSJrk2r5H8v+WVafRWz5xdSVmWLoITZQXcgehI2ZE6gioE6HirAEToM/RvFBeuhw==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.8.tgz",
"integrity": "sha512-FuzEP9BixzZohl1kLf76KEVOsxtIBFwCaLupVuk4eFVnOZfU+Wsn+x5Ryam7nILV2pkq2TqQM9EZPsOBuMC+kg==",
"cpu": [
"arm"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.8.tgz",
"integrity": "sha512-WIgg00ARWv/uYLU7lsuDK00d/hHSfES5BzdWAdAig1ioV5kaFNrtK8EqGcUBJhYqotlUByUKz5Qo6u8tt7iD/w==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ia32": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.8.tgz",
"integrity": "sha512-A1D9YzRX1i+1AJZuFFUMP1E9fMaYY+GnSQil9Tlw05utlE86EKTUA7RjwHDkEitmLYiFsRd9HwKBPEftNdBfjg==",
"cpu": [
"ia32"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-loong64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.8.tgz",
"integrity": "sha512-O7k1J/dwHkY1RMVvglFHl1HzutGEFFZ3kNiDMSOyUrB7WcoHGf96Sh+64nTRT26l3GMbCW01Ekh/ThKM5iI7hQ==",
"cpu": [
"loong64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-mips64el": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.8.tgz",
"integrity": "sha512-uv+dqfRazte3BzfMp8PAQXmdGHQt2oC/y2ovwpTteqrMx2lwaksiFZ/bdkXJC19ttTvNXBuWH53zy/aTj1FgGw==",
"cpu": [
"mips64el"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ppc64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.8.tgz",
"integrity": "sha512-GyG0KcMi1GBavP5JgAkkstMGyMholMDybAf8wF5A70CALlDM2p/f7YFE7H92eDeH/VBtFJA5MT4nRPDGg4JuzQ==",
"cpu": [
"ppc64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-riscv64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.8.tgz",
"integrity": "sha512-rAqDYFv3yzMrq7GIcen3XP7TUEG/4LK86LUPMIz6RT8A6pRIDn0sDcvjudVZBiiTcZCY9y2SgYX2lgK3AF+1eg==",
"cpu": [
"riscv64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-s390x": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.8.tgz",
"integrity": "sha512-Xutvh6VjlbcHpsIIbwY8GVRbwoviWT19tFhgdA7DlenLGC/mbc3lBoVb7jxj9Z+eyGqvcnSyIltYUrkKzWqSvg==",
"cpu": [
"s390x"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.8.tgz",
"integrity": "sha512-ASFQhgY4ElXh3nDcOMTkQero4b1lgubskNlhIfJrsH5OKZXDpUAKBlNS0Kx81jwOBp+HCeZqmoJuihTv57/jvQ==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.8.tgz",
"integrity": "sha512-d1KfruIeohqAi6SA+gENMuObDbEjn22olAR7egqnkCD9DGBG0wsEARotkLgXDu6c4ncgWTZJtN5vcgxzWRMzcw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.8.tgz",
"integrity": "sha512-nVDCkrvx2ua+XQNyfrujIG38+YGyuy2Ru9kKVNyh5jAys6n+l44tTtToqHjino2My8VAY6Lw9H7RI73XFi66Cg==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.8.tgz",
"integrity": "sha512-j8HgrDuSJFAujkivSMSfPQSAa5Fxbvk4rgNAS5i3K+r8s1X0p1uOO2Hl2xNsGFppOeHOLAVgYwDVlmxhq5h+SQ==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.8.tgz",
"integrity": "sha512-1h8MUAwa0VhNCDp6Af0HToI2TJFAn1uqT9Al6DJVzdIBAd21m/G0Yfc77KDM3uF3T/YaOgQq3qTJHPbTOInaIQ==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openharmony-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.8.tgz",
"integrity": "sha512-r2nVa5SIK9tSWd0kJd9HCffnDHKchTGikb//9c7HX+r+wHYCpQrSgxhlY6KWV1nFo1l4KFbsMlHk+L6fekLsUg==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openharmony"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/sunos-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.8.tgz",
"integrity": "sha512-zUlaP2S12YhQ2UzUfcCuMDHQFJyKABkAjvO5YSndMiIkMimPmxA+BYSBikWgsRpvyxuRnow4nS5NPnf9fpv41w==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"sunos"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-arm64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.8.tgz",
"integrity": "sha512-YEGFFWESlPva8hGL+zvj2z/SaK+pH0SwOM0Nc/d+rVnW7GSTFlLBGzZkuSU9kFIGIo8q9X3ucpZhu8PDN5A2sQ==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-ia32": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.8.tgz",
"integrity": "sha512-hiGgGC6KZ5LZz58OL/+qVVoZiuZlUYlYHNAmczOm7bs2oE1XriPFi5ZHHrS8ACpV5EjySrnoCKmcbQMN+ojnHg==",
"cpu": [
"ia32"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-x64": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.8.tgz",
"integrity": "sha512-cn3Yr7+OaaZq1c+2pe+8yxC8E144SReCQjN6/2ynubzYjvyqZjTXfQJpAcQpsdJq3My7XADANiYGHoFC69pLQw==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/esbuild": {
"version": "0.25.8",
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.8.tgz",
"integrity": "sha512-vVC0USHGtMi8+R4Kz8rt6JhEWLxsv9Rnu/lGYbPR8u47B+DCBksq9JarW0zOO7bs37hyOK1l2/oqtbciutL5+Q==",
"dev": true,
"hasInstallScript": true,
"license": "MIT",
"bin": {
"esbuild": "bin/esbuild"
},
"engines": {
"node": ">=18"
},
"optionalDependencies": {
"@esbuild/aix-ppc64": "0.25.8",
"@esbuild/android-arm": "0.25.8",
"@esbuild/android-arm64": "0.25.8",
"@esbuild/android-x64": "0.25.8",
"@esbuild/darwin-arm64": "0.25.8",
"@esbuild/darwin-x64": "0.25.8",
"@esbuild/freebsd-arm64": "0.25.8",
"@esbuild/freebsd-x64": "0.25.8",
"@esbuild/linux-arm": "0.25.8",
"@esbuild/linux-arm64": "0.25.8",
"@esbuild/linux-ia32": "0.25.8",
"@esbuild/linux-loong64": "0.25.8",
"@esbuild/linux-mips64el": "0.25.8",
"@esbuild/linux-ppc64": "0.25.8",
"@esbuild/linux-riscv64": "0.25.8",
"@esbuild/linux-s390x": "0.25.8",
"@esbuild/linux-x64": "0.25.8",
"@esbuild/netbsd-arm64": "0.25.8",
"@esbuild/netbsd-x64": "0.25.8",
"@esbuild/openbsd-arm64": "0.25.8",
"@esbuild/openbsd-x64": "0.25.8",
"@esbuild/openharmony-arm64": "0.25.8",
"@esbuild/sunos-x64": "0.25.8",
"@esbuild/win32-arm64": "0.25.8",
"@esbuild/win32-ia32": "0.25.8",
"@esbuild/win32-x64": "0.25.8"
}
},
"node_modules/gen-city": {
"version": "1.4.6",
"resolved": "https://registry.npmjs.org/gen-city/-/gen-city-1.4.6.tgz",
"integrity": "sha512-7Vw/HZvVbnDIkLkQbYffPtXp42tFsf2Szf8ptbimyTNg+Iv8ELj6hzgrlznGlRDe8MJg9gu3zISb4AEcvoFsWg==",
"license": "MIT"
}
}
}
+7
View File
@@ -0,0 +1,7 @@
{
"name": "pageswiki-city-generator",
"private": true,
"scripts": { "build": "esbuild src/adapter.js --bundle --format=iife --global-name=PagesWikiGenCity --outfile=../../static/vendor/city-generator/gen-city.bundle.js" },
"dependencies": { "gen-city": "1.4.6" },
"devDependencies": { "esbuild": "0.25.8" }
}
+22
View File
@@ -0,0 +1,22 @@
import { City, CityGenerationMode } from 'gen-city';
const seed = value => {
let state = 2166136261;
for (const char of String(value)) { state ^= char.charCodeAt(0); state = Math.imul(state, 16777619); }
return Array.from({length:256}, () => { state = Math.imul(state ^ state >>> 15, 2246822519); return Math.abs(state % 1001); });
};
export async function generateFabric(key, width = 180, height = 100) {
if (typeof key !== 'string' || !key || key.length > 256 || !Number.isInteger(width) || !Number.isInteger(height) || width < 64 || width > 320 || height < 64 || height > 240) {
throw new RangeError('City generation bounds exceeded');
}
const city = new City({width, height});
await city.generate({mode:CityGenerationMode.SEED,seed:seed(key),streetMinLength:9,probabilityIntersection:.12,probabilityTurn:.09,probabilityStreetEnd:.012,buildingMinSize:3,buildingMaxSize:7,buildingMinSpace:1,buildingMaxSpace:2,buildingOffset:1});
const fabric = {
generator:'gen-city', version:'1.4.6', width, height,
roads:city.getAllPaths().map(path => { const p=path.getPositions(); return [p.beg.x,p.beg.y,p.end.x,p.end.y]; }),
buildings:city.getAllBuildings().map(building => building.vertices.map(point => [point.x,point.y]))
};
if (fabric.roads.length > 4096 || fabric.buildings.length > 4096) throw new RangeError('City geometry budget exceeded');
return fabric;
}
+9
View File
@@ -0,0 +1,9 @@
import { build } from "esbuild";
await build({
entryPoints: ["src/editor.js"],
bundle: true,
minify: false,
sourcemap: true,
outfile: "../../static/vendor/codemirror/editor.bundle.js",
});
+871
View File
@@ -0,0 +1,871 @@
{
"name": "editor",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "editor",
"version": "1.0.0",
"license": "ISC",
"dependencies": {
"@codemirror/autocomplete": "^6.20.3",
"@codemirror/commands": "^6.10.3",
"@codemirror/lang-cpp": "^6.0.3",
"@codemirror/lang-css": "^6.3.1",
"@codemirror/lang-go": "^6.0.1",
"@codemirror/lang-html": "^6.4.11",
"@codemirror/lang-java": "^6.0.2",
"@codemirror/lang-javascript": "^6.2.5",
"@codemirror/lang-json": "^6.0.2",
"@codemirror/lang-markdown": "^6.5.0",
"@codemirror/lang-python": "^6.2.1",
"@codemirror/lang-rust": "^6.0.2",
"@codemirror/lang-sql": "^6.10.0",
"@codemirror/lang-yaml": "^6.1.3",
"@codemirror/language": "^6.12.3",
"@codemirror/legacy-modes": "^6.5.3",
"@codemirror/state": "^6.6.0",
"@codemirror/view": "^6.43.0",
"@replit/codemirror-vim": "^6.3.0",
"esbuild": "^0.28.0"
}
},
"node_modules/@codemirror/autocomplete": {
"version": "6.20.3",
"resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.3.tgz",
"integrity": "sha512-tlosUqb+3BbxCxZdu4tKeRghPFC+QM7q4X5YhKV2eCmPG+1r2F3f4AaSz5sCrFqUtX4Jh20VFTKecl16MgiV9g==",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.17.0",
"@lezer/common": "^1.0.0"
}
},
"node_modules/@codemirror/commands": {
"version": "6.10.3",
"resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.10.3.tgz",
"integrity": "sha512-JFRiqhKu+bvSkDLI+rUhJwSxQxYb759W5GBezE8Uc8mHLqC9aV/9aTC7yJSqCtB3F00pylrLCwnyS91Ap5ej4Q==",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@codemirror/state": "^6.6.0",
"@codemirror/view": "^6.27.0",
"@lezer/common": "^1.1.0"
}
},
"node_modules/@codemirror/lang-cpp": {
"version": "6.0.3",
"resolved": "https://registry.npmjs.org/@codemirror/lang-cpp/-/lang-cpp-6.0.3.tgz",
"integrity": "sha512-URM26M3vunFFn9/sm6rzqrBzDgfWuDixp85uTY49wKudToc2jTHUrKIGGKs+QWND+YLofNNZpxcNGRynFJfvgA==",
"license": "MIT",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@lezer/cpp": "^1.0.0"
}
},
"node_modules/@codemirror/lang-css": {
"version": "6.3.1",
"resolved": "https://registry.npmjs.org/@codemirror/lang-css/-/lang-css-6.3.1.tgz",
"integrity": "sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/language": "^6.0.0",
"@codemirror/state": "^6.0.0",
"@lezer/common": "^1.0.2",
"@lezer/css": "^1.1.7"
}
},
"node_modules/@codemirror/lang-go": {
"version": "6.0.1",
"resolved": "https://registry.npmjs.org/@codemirror/lang-go/-/lang-go-6.0.1.tgz",
"integrity": "sha512-7fNvbyNylvqCphW9HD6WFnRpcDjr+KXX/FgqXy5H5ZS0eC5edDljukm/yNgYkwTsgp2busdod50AOTIy6Jikfg==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/language": "^6.6.0",
"@codemirror/state": "^6.0.0",
"@lezer/common": "^1.0.0",
"@lezer/go": "^1.0.0"
}
},
"node_modules/@codemirror/lang-html": {
"version": "6.4.11",
"resolved": "https://registry.npmjs.org/@codemirror/lang-html/-/lang-html-6.4.11.tgz",
"integrity": "sha512-9NsXp7Nwp891pQchI7gPdTwBuSuT3K65NGTHWHNJ55HjYcHLllr0rbIZNdOzas9ztc1EUVBlHou85FFZS4BNnw==",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/lang-css": "^6.0.0",
"@codemirror/lang-javascript": "^6.0.0",
"@codemirror/language": "^6.4.0",
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.17.0",
"@lezer/common": "^1.0.0",
"@lezer/css": "^1.1.0",
"@lezer/html": "^1.3.12"
}
},
"node_modules/@codemirror/lang-java": {
"version": "6.0.2",
"resolved": "https://registry.npmjs.org/@codemirror/lang-java/-/lang-java-6.0.2.tgz",
"integrity": "sha512-m5Nt1mQ/cznJY7tMfQTJchmrjdjQ71IDs+55d1GAa8DGaB8JXWsVCkVT284C3RTASaY43YknrK2X3hPO/J3MOQ==",
"license": "MIT",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@lezer/java": "^1.0.0"
}
},
"node_modules/@codemirror/lang-javascript": {
"version": "6.2.5",
"resolved": "https://registry.npmjs.org/@codemirror/lang-javascript/-/lang-javascript-6.2.5.tgz",
"integrity": "sha512-zD4e5mS+50htS7F+TYjBPsiIFGanfVqg4HyUz6WNFikgOPf2BgKlx+TQedI1w6n/IqRBVBbBWmGFdLB/7uxO4A==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/language": "^6.6.0",
"@codemirror/lint": "^6.0.0",
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.17.0",
"@lezer/common": "^1.0.0",
"@lezer/javascript": "^1.0.0"
}
},
"node_modules/@codemirror/lang-json": {
"version": "6.0.2",
"resolved": "https://registry.npmjs.org/@codemirror/lang-json/-/lang-json-6.0.2.tgz",
"integrity": "sha512-x2OtO+AvwEHrEwR0FyyPtfDUiloG3rnVTSZV1W8UteaLL8/MajQd8DpvUb2YVzC+/T18aSDv0H9mu+xw0EStoQ==",
"license": "MIT",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@lezer/json": "^1.0.0"
}
},
"node_modules/@codemirror/lang-markdown": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/@codemirror/lang-markdown/-/lang-markdown-6.5.0.tgz",
"integrity": "sha512-0K40bZ35jpHya6FriukbgaleaqzBLZfOh7HuzqbMxBXkbYMJDxfF39c23xOgxFezR+3G+tR2/Mup+Xk865OMvw==",
"dependencies": {
"@codemirror/autocomplete": "^6.7.1",
"@codemirror/lang-html": "^6.0.0",
"@codemirror/language": "^6.3.0",
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.0.0",
"@lezer/common": "^1.2.1",
"@lezer/markdown": "^1.0.0"
}
},
"node_modules/@codemirror/lang-python": {
"version": "6.2.1",
"resolved": "https://registry.npmjs.org/@codemirror/lang-python/-/lang-python-6.2.1.tgz",
"integrity": "sha512-IRjC8RUBhn9mGR9ywecNhB51yePWCGgvHfY1lWN/Mrp3cKuHr0isDKia+9HnvhiWNnMpbGhWrkhuWOc09exRyw==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.3.2",
"@codemirror/language": "^6.8.0",
"@codemirror/state": "^6.0.0",
"@lezer/common": "^1.2.1",
"@lezer/python": "^1.1.4"
}
},
"node_modules/@codemirror/lang-rust": {
"version": "6.0.2",
"resolved": "https://registry.npmjs.org/@codemirror/lang-rust/-/lang-rust-6.0.2.tgz",
"integrity": "sha512-EZaGjCUegtiU7kSMvOfEZpaCReowEf3yNidYu7+vfuGTm9ow4mthAparY5hisJqOHmJowVH3Upu+eJlUji6qqA==",
"license": "MIT",
"dependencies": {
"@codemirror/language": "^6.0.0",
"@lezer/rust": "^1.0.0"
}
},
"node_modules/@codemirror/lang-sql": {
"version": "6.10.0",
"resolved": "https://registry.npmjs.org/@codemirror/lang-sql/-/lang-sql-6.10.0.tgz",
"integrity": "sha512-6ayPkEd/yRw0XKBx5uAiToSgGECo/GY2NoJIHXIIQh1EVwLuKoU8BP/qK0qH5NLXAbtJRLuT73hx7P9X34iO4w==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/language": "^6.0.0",
"@codemirror/state": "^6.0.0",
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@codemirror/lang-yaml": {
"version": "6.1.3",
"resolved": "https://registry.npmjs.org/@codemirror/lang-yaml/-/lang-yaml-6.1.3.tgz",
"integrity": "sha512-AZ8DJBuXGVHybpBQhmZtgew5//4hv3tdkXnr3vDmOUMJRuB6vn/uuwtmTOTlqEaQFg3hQSVeA90NmvIQyUV6FQ==",
"license": "MIT",
"dependencies": {
"@codemirror/autocomplete": "^6.0.0",
"@codemirror/language": "^6.0.0",
"@codemirror/state": "^6.0.0",
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.2.0",
"@lezer/lr": "^1.0.0",
"@lezer/yaml": "^1.0.0"
}
},
"node_modules/@codemirror/language": {
"version": "6.12.3",
"resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.12.3.tgz",
"integrity": "sha512-QwCZW6Tt1siP37Jet9Tb02Zs81TQt6qQrZR2H+eGMcFsL1zMrk2/b9CLC7/9ieP1fjIUMgviLWMmgiHoJrj+ZA==",
"dependencies": {
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.23.0",
"@lezer/common": "^1.5.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0",
"style-mod": "^4.0.0"
}
},
"node_modules/@codemirror/legacy-modes": {
"version": "6.5.3",
"resolved": "https://registry.npmjs.org/@codemirror/legacy-modes/-/legacy-modes-6.5.3.tgz",
"integrity": "sha512-xCsmIzH78MyWkib9jlPaaun57XNkfbMIhagfaZVd0iLTqlpw3jXaIcbZm72MTmmn64eTZpBVNjbyYh+QXnxRsg==",
"license": "MIT",
"dependencies": {
"@codemirror/language": "^6.0.0"
}
},
"node_modules/@codemirror/lint": {
"version": "6.9.6",
"resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.6.tgz",
"integrity": "sha512-6Kp7r6XfCi/D/5sdXieMfg9pJU1bUEx96WITuLU6ESaKizCz0QHFMjY/TaFSbigDdEAIgi93itLBIUETP4oK+A==",
"dependencies": {
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.42.0",
"crelt": "^1.0.5"
}
},
"node_modules/@codemirror/search": {
"version": "6.7.0",
"resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.7.0.tgz",
"integrity": "sha512-ZvGm99wc/s2cITtMT15LFdn8aH/aS+V+DqyGq/N5ZlV5vWtH+nILvC2nw0zX7ByNoHHDZ2IxxdW38O0tc5nVHg==",
"peer": true,
"dependencies": {
"@codemirror/state": "^6.0.0",
"@codemirror/view": "^6.37.0",
"crelt": "^1.0.5"
}
},
"node_modules/@codemirror/state": {
"version": "6.6.0",
"resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.6.0.tgz",
"integrity": "sha512-4nbvra5R5EtiCzr9BTHiTLc+MLXK2QGiAVYMyi8PkQd3SR+6ixar/Q/01Fa21TBIDOZXgeWV4WppsQolSreAPQ==",
"dependencies": {
"@marijn/find-cluster-break": "^1.0.0"
}
},
"node_modules/@codemirror/view": {
"version": "6.43.0",
"resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.43.0.tgz",
"integrity": "sha512-V7ZCLQO3Jus9hzh2jVCCPW3mO4IBMr43O37PqSUYautJSnnJF41YlgLw21x0fLJTYvJ+Vkm6Gp+qKGH9pltgXA==",
"dependencies": {
"@codemirror/state": "^6.6.0",
"crelt": "^1.0.6",
"style-mod": "^4.1.0",
"w3c-keyname": "^2.2.4"
}
},
"node_modules/@esbuild/aix-ppc64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
"integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
"cpu": [
"ppc64"
],
"optional": true,
"os": [
"aix"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
"integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
"cpu": [
"arm"
],
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
"integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
"integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
"integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
"integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
"integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
"integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
"integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
"cpu": [
"arm"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
"integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ia32": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
"integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
"cpu": [
"ia32"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-loong64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
"integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
"cpu": [
"loong64"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-mips64el": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
"integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
"cpu": [
"mips64el"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ppc64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
"integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
"cpu": [
"ppc64"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-riscv64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
"integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
"cpu": [
"riscv64"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-s390x": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
"integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
"cpu": [
"s390x"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
"integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
"integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
"integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
"integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
"integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openharmony-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
"integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"openharmony"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/sunos-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
"integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"sunos"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-arm64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
"integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
"cpu": [
"arm64"
],
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-ia32": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
"integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
"cpu": [
"ia32"
],
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-x64": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
"integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
"cpu": [
"x64"
],
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@lezer/common": {
"version": "1.5.2",
"resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",
"integrity": "sha512-sxQE460fPZyU3sdc8lafxiPwJHBzZRy/udNFynGQky1SePYBdhkBl1kOagA9uT3pxR8K09bOrmTUqA9wb/PjSQ=="
},
"node_modules/@lezer/cpp": {
"version": "1.1.6",
"resolved": "https://registry.npmjs.org/@lezer/cpp/-/cpp-1.1.6.tgz",
"integrity": "sha512-vh9gWWJOXFVY8HBHK3Twzq8MgwG2iN4GSyzBP9sCGTe37P15x2R14VaBQk0VA0ezTRN1KHYBBsHhvpGZ2Xy/pA==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/css": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@lezer/css/-/css-1.3.3.tgz",
"integrity": "sha512-RzBo8r+/6QJeow7aPHIpGVIH59xTcJXp399820gZoMo9noQDRVpJLheIBUicYwKcsbOYoBRoLZlf2720dG/4Tg==",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.3.0"
}
},
"node_modules/@lezer/go": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@lezer/go/-/go-1.0.1.tgz",
"integrity": "sha512-xToRsYxwsgJNHTgNdStpcvmbVuKxTapV0dM0wey1geMMRc9aggoVyKgzYp41D2/vVOx+Ii4hmE206kvxIXBVXQ==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.3.0"
}
},
"node_modules/@lezer/highlight": {
"version": "1.2.3",
"resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.3.tgz",
"integrity": "sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g==",
"dependencies": {
"@lezer/common": "^1.3.0"
}
},
"node_modules/@lezer/html": {
"version": "1.3.13",
"resolved": "https://registry.npmjs.org/@lezer/html/-/html-1.3.13.tgz",
"integrity": "sha512-oI7n6NJml729m7pjm9lvLvmXbdoMoi2f+1pwSDJkl9d68zGr7a9Btz8NdHTGQZtW2DA25ybeuv/SyDb9D5tseg==",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/java": {
"version": "1.1.3",
"resolved": "https://registry.npmjs.org/@lezer/java/-/java-1.1.3.tgz",
"integrity": "sha512-yHquUfujwg6Yu4Fd1GNHCvidIvJwi/1Xu2DaKl/pfWIA2c1oXkVvawH3NyXhCaFx4OdlYBVX5wvz2f7Aoa/4Xw==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/javascript": {
"version": "1.5.4",
"resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.5.4.tgz",
"integrity": "sha512-vvYx3MhWqeZtGPwDStM2dwgljd5smolYD2lR2UyFcHfxbBQebqx8yjmFmxtJ/E6nN6u1D9srOiVWm3Rb4tmcUA==",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.1.3",
"@lezer/lr": "^1.3.0"
}
},
"node_modules/@lezer/json": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/@lezer/json/-/json-1.0.3.tgz",
"integrity": "sha512-BP9KzdF9Y35PDpv04r0VeSTKDeox5vVr3efE7eBbx3r4s3oNLfunchejZhjArmeieBH+nVOpgIiBJpEAv8ilqQ==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/lr": {
"version": "1.4.10",
"resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.10.tgz",
"integrity": "sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==",
"dependencies": {
"@lezer/common": "^1.0.0"
}
},
"node_modules/@lezer/markdown": {
"version": "1.6.4",
"resolved": "https://registry.npmjs.org/@lezer/markdown/-/markdown-1.6.4.tgz",
"integrity": "sha512-N0SxazMj4k65DBfaf1azqtMZd6u7MqluP84/NZnB/io8Td9aleFmAhz9hcbvSfsxT5tdYlJ5qgv5aMJGY4zEtA==",
"dependencies": {
"@lezer/common": "^1.5.0",
"@lezer/highlight": "^1.0.0"
}
},
"node_modules/@lezer/python": {
"version": "1.1.19",
"resolved": "https://registry.npmjs.org/@lezer/python/-/python-1.1.19.tgz",
"integrity": "sha512-MhQIURHRytsNzP/YXnqpYKW6la6voAH3kyplTOOiCdjyFY6cWWGFVmYVdHIPrElqSDf4iCDktQCockB9FxuhzQ==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/rust": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/@lezer/rust/-/rust-1.0.2.tgz",
"integrity": "sha512-Lz5sIPBdF2FUXcWeCu1//ojFAZqzTQNRga0aYv6dYXqJqPfMdCAI0NzajWUd4Xijj1IKJLtjoXRPMvTKWBcqKg==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.0.0"
}
},
"node_modules/@lezer/yaml": {
"version": "1.0.4",
"resolved": "https://registry.npmjs.org/@lezer/yaml/-/yaml-1.0.4.tgz",
"integrity": "sha512-2lrrHqxalACEbxIbsjhqGpSW8kWpUKuY6RHgnSAFZa6qK62wvnPxA8hGOwOoDbwHcOFs5M4o27mjGu+P7TvBmw==",
"license": "MIT",
"dependencies": {
"@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.0.0",
"@lezer/lr": "^1.4.0"
}
},
"node_modules/@marijn/find-cluster-break": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.2.tgz",
"integrity": "sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g=="
},
"node_modules/@replit/codemirror-vim": {
"version": "6.3.0",
"resolved": "https://registry.npmjs.org/@replit/codemirror-vim/-/codemirror-vim-6.3.0.tgz",
"integrity": "sha512-aTx931ULAMuJx6xLf7KQDOL7CxD+Sa05FktTDrtLaSy53uj01ll3Zf17JdKsriER248oS55GBzg0CfCTjEneAQ==",
"peerDependencies": {
"@codemirror/commands": "6.x.x",
"@codemirror/language": "6.x.x",
"@codemirror/search": "6.x.x",
"@codemirror/state": "6.x.x",
"@codemirror/view": "6.x.x"
}
},
"node_modules/crelt": {
"version": "1.0.6",
"resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.6.tgz",
"integrity": "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g=="
},
"node_modules/esbuild": {
"version": "0.28.0",
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
"integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
"hasInstallScript": true,
"bin": {
"esbuild": "bin/esbuild"
},
"engines": {
"node": ">=18"
},
"optionalDependencies": {
"@esbuild/aix-ppc64": "0.28.0",
"@esbuild/android-arm": "0.28.0",
"@esbuild/android-arm64": "0.28.0",
"@esbuild/android-x64": "0.28.0",
"@esbuild/darwin-arm64": "0.28.0",
"@esbuild/darwin-x64": "0.28.0",
"@esbuild/freebsd-arm64": "0.28.0",
"@esbuild/freebsd-x64": "0.28.0",
"@esbuild/linux-arm": "0.28.0",
"@esbuild/linux-arm64": "0.28.0",
"@esbuild/linux-ia32": "0.28.0",
"@esbuild/linux-loong64": "0.28.0",
"@esbuild/linux-mips64el": "0.28.0",
"@esbuild/linux-ppc64": "0.28.0",
"@esbuild/linux-riscv64": "0.28.0",
"@esbuild/linux-s390x": "0.28.0",
"@esbuild/linux-x64": "0.28.0",
"@esbuild/netbsd-arm64": "0.28.0",
"@esbuild/netbsd-x64": "0.28.0",
"@esbuild/openbsd-arm64": "0.28.0",
"@esbuild/openbsd-x64": "0.28.0",
"@esbuild/openharmony-arm64": "0.28.0",
"@esbuild/sunos-x64": "0.28.0",
"@esbuild/win32-arm64": "0.28.0",
"@esbuild/win32-ia32": "0.28.0",
"@esbuild/win32-x64": "0.28.0"
}
},
"node_modules/style-mod": {
"version": "4.1.3",
"resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.3.tgz",
"integrity": "sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ=="
},
"node_modules/w3c-keyname": {
"version": "2.2.8",
"resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
"integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ=="
}
}
}
+34
View File
@@ -0,0 +1,34 @@
{
"name": "editor",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"@codemirror/autocomplete": "^6.20.3",
"@codemirror/commands": "^6.10.3",
"@codemirror/lang-cpp": "^6.0.3",
"@codemirror/lang-css": "^6.3.1",
"@codemirror/lang-go": "^6.0.1",
"@codemirror/lang-html": "^6.4.11",
"@codemirror/lang-java": "^6.0.2",
"@codemirror/lang-javascript": "^6.2.5",
"@codemirror/lang-json": "^6.0.2",
"@codemirror/lang-markdown": "^6.5.0",
"@codemirror/lang-python": "^6.2.1",
"@codemirror/lang-rust": "^6.0.2",
"@codemirror/lang-sql": "^6.10.0",
"@codemirror/lang-yaml": "^6.1.3",
"@codemirror/language": "^6.12.3",
"@codemirror/legacy-modes": "^6.5.3",
"@codemirror/state": "^6.6.0",
"@codemirror/view": "^6.43.0",
"@replit/codemirror-vim": "^6.3.0",
"esbuild": "^0.28.0"
}
}
+487
View File
@@ -0,0 +1,487 @@
import { EditorView, keymap, lineNumbers } from "@codemirror/view";
import { EditorState } from "@codemirror/state";
import { defaultKeymap, history, historyKeymap } from "@codemirror/commands";
import {
bracketMatching,
defaultHighlightStyle,
StreamLanguage,
syntaxHighlighting,
} from "@codemirror/language";
import {
autocompletion,
completionKeymap,
closeBrackets,
closeBracketsKeymap,
} from "@codemirror/autocomplete";
import { html } from "@codemirror/lang-html";
import { markdown } from "@codemirror/lang-markdown";
import { javascript } from "@codemirror/lang-javascript";
import { python } from "@codemirror/lang-python";
import { json } from "@codemirror/lang-json";
import { css } from "@codemirror/lang-css";
import { sql } from "@codemirror/lang-sql";
import { yaml } from "@codemirror/lang-yaml";
import { go } from "@codemirror/lang-go";
import { rust } from "@codemirror/lang-rust";
import { java } from "@codemirror/lang-java";
import { cpp } from "@codemirror/lang-cpp";
import { shell } from "@codemirror/legacy-modes/mode/shell";
import { toml } from "@codemirror/legacy-modes/mode/toml";
import { vim, Vim } from "@replit/codemirror-vim";
const pagesWikiTheme = EditorView.theme({
".cm-selectionBackground": {
backgroundColor: "rgba(255, 216, 102, 0.48) !important",
},
"&.cm-focused .cm-selectionBackground": {
backgroundColor: "rgba(255, 216, 102, 0.58) !important",
},
".cm-selectionLayer .cm-selectionBackground": {
backgroundColor: "rgba(255, 216, 102, 0.58) !important",
},
".cm-content ::selection": {
backgroundColor: "rgba(255, 216, 102, 0.48) !important",
color: "#ffffff !important",
},
});
let vimMode = "INSERT";
function languageExtension(mode) {
switch (String(mode || "").toLowerCase()) {
case "html":
return html();
case "markdown":
return markdown();
case "javascript":
return javascript({ jsx: true });
case "typescript":
return javascript({ jsx: true, typescript: true });
case "python":
return python();
case "json":
return json();
case "css":
return css();
case "sql":
return sql();
case "yaml":
return yaml();
case "go":
return go();
case "rust":
return rust();
case "java":
return java();
case "cpp":
return cpp();
case "shell":
return StreamLanguage.define(shell);
case "toml":
return StreamLanguage.define(toml);
default:
return null;
}
}
function attachMinimap(view, minimap, text) {
if (!minimap) {
return;
}
const lines = text.split("\n");
const count = Math.max(lines.length, 1);
const step = Math.max(1, Math.ceil(count / 2000));
for (let index = 0; index < count; index += step) {
const line = document.createElement("span");
line.className = "content-code-minimap-line";
line.style.top = (index / count * 100) + "%";
const length = (lines[index] || "").trimEnd().length;
line.style.width = Math.min(96, Math.max(3, length * 1.4)) + "%";
minimap.appendChild(line);
}
const viewport = document.createElement("span");
viewport.className = "content-code-minimap-viewport";
minimap.appendChild(viewport);
const scroller = view.scrollDOM;
const update = () => {
const scrollHeight = Math.max(scroller.scrollHeight, 1);
viewport.style.top =
(scroller.scrollTop / scrollHeight * 100) + "%";
viewport.style.height =
Math.min(100, scroller.clientHeight / scrollHeight * 100) + "%";
};
scroller.addEventListener("scroll", update, { passive: true });
new ResizeObserver(update).observe(scroller);
minimap.addEventListener("pointerdown", (event) => {
const rect = minimap.getBoundingClientRect();
const ratio = Math.max(
0,
Math.min(1, (event.clientY - rect.top) / rect.height),
);
scroller.scrollTop =
ratio * scroller.scrollHeight - scroller.clientHeight / 2;
});
update();
}
function setEditorMode(mode) {
vimMode = mode;
const el =
document.getElementById("editor-vim-mode");
if (!el) {
return;
}
const cls =
"mode-" + mode.toLowerCase();
el.innerHTML =
"<strong class=\"" + cls + "\">" + mode + "</strong>";
}
function markdownCompletions(context) {
const word =
context.matchBefore(/[A-Za-z#`\-\[\]\{\}:\/]*/);
if (!word || (word.from === word.to && !context.explicit)) {
return null;
}
return {
from: word.from,
options: [
{ label: "# ", type: "keyword", apply: "# " },
{ label: "## ", type: "keyword", apply: "## " },
{ label: "### ", type: "keyword", apply: "### " },
{ label: "- ", type: "keyword", apply: "- " },
{ label: "```text", type: "snippet", apply: "```text\n\n```" },
{ label: "```go", type: "snippet", apply: "```go\n\n```" },
{ label: "```bash", type: "snippet", apply: "```bash\n\n```" },
{ label: "[link](url)", type: "snippet", apply: "[text](url)" },
{ label: "{{children}}", type: "function", apply: "{{children}}" },
{ label: "{{children:/}}", type: "function", apply: "{{children:/}}" },
{ label: "{{children:/ exclude=/draft}}", type: "function", apply: "{{children:/ exclude=/draft}}" },
],
};
}
function installVimCommands() {
if (!Vim || !Vim.defineEx || window.PagesWikiVimCommandsInstalled) {
return;
}
window.PagesWikiVimCommandsInstalled = true;
const save =
() => {
if (window.PagesEditor && window.PagesEditor.saveNow) {
window.PagesEditor.saveNow();
}
};
const quit =
() => {
location.href =
window.PagesWikiCurrentPath || "/";
};
const saveQuit =
() => {
save();
setTimeout(quit, 120);
};
// Register both canonical and short names.
Vim.defineEx("write", "w", save);
Vim.defineEx("w", "w", save);
Vim.defineEx("quit", "q", quit);
Vim.defineEx("q", "q", quit);
Vim.defineEx("wq", "wq", saveQuit);
Vim.defineEx("x", "x", saveQuit);
}
function attachVimModeTracking(view) {
view.dom.addEventListener(
"keydown",
(ev) => {
if (ev.key === "Escape" || (ev.ctrlKey && ev.key === "[")) {
setEditorMode("NORMAL");
return;
}
if (vimMode === "NORMAL") {
if (ev.key === "i" || ev.key === "a" || ev.key === "o" || ev.key === "O") {
setEditorMode("INSERT");
return;
}
if (ev.key === "R") {
setEditorMode("REPLACE");
return;
}
if (ev.key === "v" || ev.key === "V") {
setEditorMode("VISUAL");
return;
}
}
if (vimMode === "VISUAL" && ev.key === "Escape") {
setEditorMode("NORMAL");
}
},
true
);
view.dom.addEventListener(
"focusin",
() => {
if (!vimMode) {
setEditorMode("INSERT");
}
}
);
}
function attachStatusBar(view) {
const cursorEl =
document.getElementById("editor-cursor");
function updateCursor() {
if (!cursorEl) {
return;
}
const head =
view.state.selection.main.head;
const line =
view.state.doc.lineAt(head);
cursorEl.textContent =
"Ln " +
line.number +
", Col " +
String(head - line.from + 1);
}
updateCursor();
setEditorMode(vimMode || "INSERT");
view.dom.addEventListener("keyup", updateCursor);
view.dom.addEventListener("mouseup", updateCursor);
view.dom.addEventListener("focusin", updateCursor);
}
window.PagesWikiEditor = {
createViewer(target, text, mode, minimap) {
const extensions = [
lineNumbers(),
syntaxHighlighting(defaultHighlightStyle),
pagesWikiTheme,
EditorState.readOnly.of(true),
EditorView.editable.of(false),
];
const language = languageExtension(mode);
if (language) {
extensions.push(language);
}
const view = new EditorView({
state: EditorState.create({
doc: text,
extensions,
}),
parent: target,
});
attachMinimap(view, minimap, text);
return view;
},
create(target, initialText, mode, options = {}) {
const keymapName =
String(options.keymap || "default").toLowerCase();
const extensions = [
lineNumbers(),
history(),
bracketMatching(),
closeBrackets(),
pagesWikiTheme,
EditorView.lineWrapping,
EditorView.updateListener.of((update) => {
if (update.docChanged) {
schedulePagesWikiPreview(update.view);
}
}),
];
if (keymapName === "vim") {
installVimCommands();
extensions.push(vim());
setEditorMode("NORMAL");
} else {
setEditorMode("INSERT");
}
extensions.push(
keymap.of([
...defaultKeymap,
...historyKeymap,
...completionKeymap,
...closeBracketsKeymap,
])
);
if (options.syntax !== false) {
extensions.push(syntaxHighlighting(defaultHighlightStyle));
}
if (options.autocomplete !== false) {
extensions.push(
autocompletion({
activateOnTyping: true,
override: mode === "markdown"
? [markdownCompletions]
: undefined,
})
);
}
const language = languageExtension(mode);
if (language) {
extensions.push(language);
}
const view =
new EditorView({
state: EditorState.create({
doc: initialText,
extensions,
}),
parent: target,
});
attachStatusBar(view);
if (keymapName === "vim") {
attachVimModeTracking(view);
attachPagesWikiExFallback(view);
}
return view;
},
};
function attachPagesWikiExFallback(view) {
let active = false;
let buffer = "";
function save() {
if (window.PagesEditor && window.PagesEditor.saveNow) {
window.PagesEditor.saveNow();
}
}
function quit() {
location.href =
window.PagesWikiCurrentPath || "/";
}
view.dom.addEventListener(
"keydown",
(ev) => {
if (!active && vimMode === "NORMAL" && ev.key === ":") {
active = true;
buffer = "";
return;
}
if (!active) {
return;
}
if (ev.key === "Escape" || (ev.ctrlKey && ev.key === "[")) {
active = false;
buffer = "";
return;
}
if (ev.key === "Enter") {
const cmd =
buffer.trim();
active = false;
buffer = "";
if (cmd === "w") {
ev.preventDefault();
save();
return;
}
if (cmd === "q") {
ev.preventDefault();
quit();
return;
}
if (cmd === "wq" || cmd === "x") {
ev.preventDefault();
save();
setTimeout(quit, 120);
return;
}
return;
}
if (ev.key.length === 1) {
buffer += ev.key;
}
if (ev.key === "Backspace") {
buffer =
buffer.slice(0, -1);
}
},
true
);
}
let pagesWikiPreviewTimer = null;
function schedulePagesWikiPreview(view) {
const textarea =
document.getElementById("editor");
if (textarea) {
textarea.value =
view.state.doc.toString();
}
if (pagesWikiPreviewTimer) {
clearTimeout(pagesWikiPreviewTimer);
}
pagesWikiPreviewTimer =
setTimeout(
() => {
if (
window.PagesEditor &&
window.PagesEditor.renderPreview
) {
window.PagesEditor.renderPreview();
}
},
350
);
}
+17
View File
@@ -0,0 +1,17 @@
{
"id": "org.pageswiki.excalidraw-viewer",
"type": "projection",
"version": "0.1.0",
"pageswiki": ">=0.1.0",
"entry_point": "/_/adaptor/excalidraw/",
"media_types": ["application/json"],
"extensions": [".excalidraw"],
"capabilities": ["revision.read"],
"outbound_hosts": [],
"limits": {
"input_bytes": 2097152,
"elements": 5000,
"points": 100000
},
"health_probe": "/_/adaptor/excalidraw/health"
}
+12
View File
@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Excalidraw Viewer</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.jsx"></script>
</body>
</html>
+19
View File
@@ -0,0 +1,19 @@
server {
listen 8080;
server_name _;
root /usr/share/nginx/html;
location = /health {
default_type text/plain;
return 200 "ok\n";
}
location / {
try_files $uri $uri/ /index.html;
add_header Cache-Control "public, max-age=31536000, immutable" always;
}
location = /index.html {
add_header Cache-Control "no-cache" always;
}
}
File diff suppressed because it is too large. Load diff
+27
View File
@@ -0,0 +1,27 @@
{
"name": "pageswiki-excalidraw-viewer",
"private": true,
"version": "0.1.0",
"type": "module",
"scripts": {
"build": "vite build"
},
"dependencies": {
"@excalidraw/excalidraw": "0.18.1",
"react": "18.3.1",
"react-dom": "18.3.1"
},
"devDependencies": {
"@vitejs/plugin-react": "5.1.4",
"vite": "7.3.6"
},
"overrides": {
"@excalidraw/excalidraw": {
"nanoid": "3.3.18"
},
"@excalidraw/mermaid-to-excalidraw": {
"nanoid": "5.1.16"
},
"lodash-es": "4.18.1"
}
}
+112
View File
@@ -0,0 +1,112 @@
import React, { useEffect, useState } from "react"
import { createRoot } from "react-dom/client"
import { Excalidraw } from "@excalidraw/excalidraw"
import "@excalidraw/excalidraw/index.css"
import "./viewer.css"
const MAX_SCENE_BYTES = 2 * 1024 * 1024
const notifyParent = (type, detail = "") => {
window.parent.postMessage({ source: "pageswiki-excalidraw", type, detail }, window.location.origin)
}
const sceneURL = () => {
const value = new URLSearchParams(window.location.search).get("url") || ""
const parsed = new URL(value, window.location.origin)
if (parsed.origin !== window.location.origin || !parsed.pathname.startsWith("/v/raw/rev:")) {
throw new Error("An immutable same-origin Revision URL is required")
}
return parsed.href
}
const readBoundedText = async response => {
const declared = Number(response.headers.get("content-length") || 0)
if (declared > MAX_SCENE_BYTES) throw new Error("Scene exceeds the 2 MiB viewer limit")
if (!response.body) return response.text()
const reader = response.body.getReader()
const chunks = []
let size = 0
while (true) {
const { done, value } = await reader.read()
if (done) break
size += value.byteLength
if (size > MAX_SCENE_BYTES) {
await reader.cancel()
throw new Error("Scene exceeds the 2 MiB viewer limit")
}
chunks.push(value)
}
const joined = new Uint8Array(size)
let offset = 0
chunks.forEach(chunk => {
joined.set(chunk, offset)
offset += chunk.byteLength
})
return new TextDecoder().decode(joined)
}
function Viewer() {
const [scene, setScene] = useState(null)
const [error, setError] = useState("")
useEffect(() => {
const controller = new AbortController()
;(async () => {
try {
const response = await fetch(sceneURL(), {
credentials: "same-origin",
cache: "force-cache",
signal: controller.signal,
headers: { Accept: "application/json" }
})
if (!response.ok) throw new Error(`Revision fetch failed: HTTP ${response.status}`)
const loaded = JSON.parse(await readBoundedText(response))
if (loaded?.type !== "excalidraw" || !Array.isArray(loaded.elements)) {
throw new Error("Invalid Excalidraw scene")
}
setScene(loaded)
} catch (reason) {
if (reason?.name === "AbortError") return
const message = reason instanceof Error ? reason.message : String(reason)
setError(message)
notifyParent("error", message)
}
})()
return () => controller.abort()
}, [])
if (error) return <main className="viewer-status viewer-error">{error}</main>
if (!scene) return <main className="viewer-status">Loading Excalidraw…</main>
return (
<main className="viewer-shell">
<Excalidraw
initialData={{
elements: scene.elements,
appState: scene.appState,
files: scene.files
}}
viewModeEnabled
zenModeEnabled
langCode={(navigator.language || "en").toLowerCase().startsWith("ja") ? "ja-JP" : "en"}
UIOptions={{
canvasActions: {
changeViewBackgroundColor: false,
clearCanvas: false,
export: false,
loadScene: false,
saveAsImage: false,
saveToActiveFile: false,
toggleTheme: true
}
}}
excalidrawAPI={api => {
requestAnimationFrame(() => api.scrollToContent(undefined, { fitToContent: true }))
notifyParent("ready")
}}
/>
</main>
)
}
createRoot(document.getElementById("root")).render(<Viewer />)
+24
View File
@@ -0,0 +1,24 @@
html,
body,
#root,
.viewer-shell {
width: 100%;
height: 100%;
margin: 0;
overflow: hidden;
}
.viewer-status {
display: grid;
place-items: center;
width: 100%;
height: 100%;
margin: 0;
font: 14px/1.5 system-ui, sans-serif;
color: #555;
background: #fff;
}
.viewer-error {
color: #9d2020;
}
+14
View File
@@ -0,0 +1,14 @@
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
export default defineConfig({
base: "./",
plugins: [react()],
define: {
"process.env.IS_PREACT": JSON.stringify("false")
},
build: {
sourcemap: false,
chunkSizeWarningLimit: 2500
}
})
+9
View File
@@ -0,0 +1,9 @@
@font-face { font-family: PagesWikiHack; src: url('./HackNerdFont-Regular.ttf') format('truetype'); font-weight:400; font-style:normal; font-display:block; }
:root { color-scheme: dark; font-family: PagesWikiHack, ui-monospace, monospace; }
* { box-sizing: border-box; }
html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: #282c34; }
body { display: block; }
main { position: relative; width: 100%; height: 100%; }
#vim-canvas { display: block; width: 100%; height: 100%; }
#vim-input { position: fixed; width: 1px; height: 1px; opacity: 0; pointer-events: none; }
#error { position: fixed; inset: 1rem 1rem auto; z-index: 2; padding: 1rem; white-space: pre-wrap; color: #ffd7d7; background: #721c24; border-radius: 6px; }
+110
View File
@@ -0,0 +1,110 @@
import {VimWasm, checkBrowserCompatibility} from "./vendor/vimwasm.js"
const errorBox = document.getElementById("error")
const fail = error => {
errorBox.hidden = false
errorBox.textContent = error instanceof Error ? error.message : String(error)
}
const compatibilityError = checkBrowserCompatibility()
if (compatibilityError || !crossOriginIsolated) {
fail(compatibilityError || "Cross-origin isolation is not active. Check COOP/COEP headers.")
} else {
try {
const response = await fetch("./api/session", {cache: "no-store", credentials: "same-origin"})
if (!response.ok) throw new Error(`Workspace request failed: HTTP ${response.status}`)
const workspace = await response.json()
const files = {}
const directories = new Set(["/work"])
for (const file of workspace.files || []) {
const path = `/work/${file.path}`
files[path] = file.content
const parts = path.split("/").slice(1, -1)
let directory = ""
for (const part of parts) {
directory += `/${part}`
directories.add(directory)
}
}
const vimrcResponse = await fetch("./vimrc", {cache: "no-store"})
if (!vimrcResponse.ok) throw new Error(`vimrc request failed: HTTP ${vimrcResponse.status}`)
// The pinned runtime creates files with wx+ and silently skips the
// bundled /.vim/vimrc. Use a new path and an explicit -u argument.
files["/pageswiki.vimrc"] = await vimrcResponse.text()
// Font metrics must be final before Vim sizes its canvas/cell grid.
await document.fonts.load('16px PagesWikiHack')
const pluginResponse = await fetch('./pageswiki.vim', {cache: 'no-store'})
if (!pluginResponse.ok) throw new Error(`Plugin request failed: HTTP ${pluginResponse.status}`)
files['/.vim/plugin/pageswiki.vim'] = await pluginResponse.text()
directories.add('/.vim')
directories.add('/.vim/plugin')
const safeMode = new URLSearchParams(location.search).get('safe') === '1'
const settings = safeMode ? {} : (workspace.vim_settings || {})
const fontSize = Number.isInteger(settings.font_size) && settings.font_size >= 10 && settings.font_size <= 32 ? settings.font_size : 16
let userConfig = `\nset guifont=PagesWikiHack:h${fontSize}\n`
if (settings.enabled) {
if (settings.colorscheme) {
directories.add('/pageswiki-config')
directories.add('/pageswiki-config/colors')
files['/pageswiki-config/colors/pageswiki_custom.vim'] = settings.colorscheme
if (/^[A-Za-z0-9_-]+\.vim$/.test(settings.color_name || '')) {
files[`/pageswiki-config/colors/${settings.color_name}`] = settings.colorscheme
}
userConfig += 'set runtimepath^=/pageswiki-config\n'
}
if (settings.vimrc) {
files['/pageswiki-user.vimrc'] = settings.vimrc
userConfig += 'source /pageswiki-user.vimrc\n'
}
if (settings.colorscheme) userConfig += 'colorscheme pageswiki_custom\n'
}
files['/pageswiki.vimrc'] += userConfig
const vim = new VimWasm({
canvas: document.getElementById("vim-canvas"),
input: document.getElementById("vim-input"),
workerScriptPath: "./vendor/vim.js"
})
vim.onVimInit = () => {
vim.focus()
}
vim.onVimExit = () => {
window.close()
document.body.textContent = "Vim exited. You may close this tab."
}
vim.onTitleUpdate = title => { document.title = `${title} · vim.wasm` }
vim.onError = fail
vim.onFileExport = async (fullpath, contents) => {
try {
const bytes = new Uint8Array(contents)
let binary = ""
for (let offset = 0; offset < bytes.length; offset += 0x8000) {
binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000))
}
const save = await fetch("./api/save", {
method: "PUT",
credentials: "same-origin",
headers: {"Content-Type": "application/json"},
body: JSON.stringify({path: fullpath, content_base64: btoa(binary)})
})
if (!save.ok) throw new Error((await save.text()).trim() || `Save failed: HTTP ${save.status}`)
} catch (error) {
fail(error)
await vim.showError(String(error))
}
}
const paths = (workspace.files || []).map(file => `/work/${file.path}`).sort()
const initial = `/work/${workspace.initial}`
const cmdArgs = ['-u', '/pageswiki.vimrc', initial, ...paths.filter(path => path !== initial)]
vim.start({
dirs: Array.from(directories).sort((a, b) => a.split("/").length - b.split("/").length),
files,
clipboard: Boolean(navigator.clipboard),
cmdArgs
})
} catch (error) {
fail(error)
}
}
+17
View File
@@ -0,0 +1,17 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Pages Wiki · vim.wasm</title>
<link rel="stylesheet" href="app.css">
</head>
<body>
<main>
<canvas id="vim-canvas"></canvas>
<input id="vim-input" autocomplete="off" autofocus aria-label="Vim keyboard input">
</main>
<div id="error" role="alert" hidden></div>
<script type="module" src="app.js"></script>
</body>
</html>
+12
View File
@@ -0,0 +1,12 @@
" Small, bundled, pure Vimscript workspace navigation. No shell or network.
if exists('g:loaded_pageswiki') | finish | endif
let g:loaded_pageswiki = 1
set path=/work/**
set wildignore+=*.swp,*.bak
command! Files call feedkeys(':find ', 'n')
nnoremap <silent> <leader>f :Files<CR>
nnoremap <leader>b :ls<CR>:buffer<Space>
nnoremap <silent> ]b :bnext<CR>
nnoremap <silent> [b :bprevious<CR>
nnoremap <silent> <leader>w :write<CR>
nnoremap <silent> <leader>/ :nohlsearch<CR>
+55
View File
@@ -0,0 +1,55 @@
set nocompatible
set runtimepath^=/.vim
set number
set guifont=PagesWikiHack:h16
set background=dark
set cursorline
set laststatus=2
set showcmd
set ruler
set scrolloff=4
set sidescrolloff=4
set noswapfile
set nobackup
set nowritebackup
set display+=lastline
set linebreak
set listchars=tab:»\ ,trail:·,extends:›,precedes:‹
let mapleader = " "
set hidden
set encoding=utf-8
set fileencoding=utf-8
set mouse=a
set backspace=indent,eol,start
set wildmenu
set wildmode=longest:full,full
set incsearch
set hlsearch
set ignorecase
set smartcase
set autoindent
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4
syntax enable
filetype plugin indent on
highlight Normal guifg=#e6edf3 guibg=#1e222a
highlight LineNr guifg=#8994a6 guibg=#1e222a
highlight CursorLine guibg=#2b3240
highlight StatusLine guifg=#e6edf3 guibg=#35415a gui=NONE
" Close the hosted Vim session with :q even when the argument list contains
" more files. Unsaved buffers still require :q! explicitly.
cnoreabbrev <expr> q getcmdtype() ==# ':' && getcmdline() ==# 'q' ? 'qa' : 'q'
cnoreabbrev <expr> q! getcmdtype() ==# ':' && getcmdline() ==# 'q!' ? 'qa!' : 'q!'
" Pages Wiki writes each exported buffer as a new Revision.
augroup pageswiki
autocmd!
autocmd BufWritePost /work/* execute 'export ' . expand('%:p')
augroup END
" Pure Vimscript plugins are preloaded into /.vim/plugin by app.js.
" vim-plug installation and fzf's native executable do not work in MEMFS.
" Vendoring fzf.vim alone does not remove that native dependency.
+21
View File
@@ -0,0 +1,21 @@
{
"name": "pageswiki-vimwasm-adapter",
"version": "0.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "pageswiki-vimwasm-adapter",
"version": "0.1.0",
"dependencies": {
"vim-wasm": "0.0.13"
}
},
"node_modules/vim-wasm": {
"version": "0.0.13",
"resolved": "https://registry.npmjs.org/vim-wasm/-/vim-wasm-0.0.13.tgz",
"integrity": "sha512-2EkJ4OfMgvA/bURJeu43wqIQ4tpCJymst++Y4R/AKuQlnrvdI4hTpG2jf0yL5TrLt1ui12leLRghrwPOybyu8w==",
"license": "Vim"
}
}
}
+8
View File
@@ -0,0 +1,8 @@
{
"name": "pageswiki-vimwasm-adapter",
"private": true,
"version": "0.1.0",
"dependencies": {
"vim-wasm": "0.0.13"
}
}
+515
View File
@@ -0,0 +1,515 @@
package main
import (
"bytes"
"crypto/rand"
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"html/template"
"io"
"log"
"net/http"
"net/http/httputil"
"net/url"
"os"
"path/filepath"
"strings"
"sync"
"time"
)
type gatewaySession struct {
VimSettings json.RawMessage
Token string
PluginID string
Filename string
ContentType string
ExpiresAtMS int64
Workspace string
Files map[string]gatewayFile
LastError string
}
type gatewayFile struct {
SemanticPath string
RevisionUUID string
LastContent string
}
type gateway struct {
origin string
client *http.Client
mu sync.Mutex
sessions map[string]gatewaySession
codeProxy *httputil.ReverseProxy
excalidrawProxy *httputil.ReverseProxy
}
func main() {
origin := strings.TrimRight(os.Getenv("PAGESWIKI_ORIGIN"), "/")
if origin == "" {
origin = "http://app:3000"
}
codeOrigin := os.Getenv("CODE_SERVER_ORIGIN")
if codeOrigin == "" {
codeOrigin = "http://code-server:8080"
}
codeURL, err := url.Parse(codeOrigin)
if err != nil {
log.Fatal(err)
}
proxy := httputil.NewSingleHostReverseProxy(codeURL)
originalDirector := proxy.Director
proxy.Director = func(req *http.Request) {
req.URL.Path = strings.TrimPrefix(req.URL.Path, "/code")
if req.URL.Path == "" {
req.URL.Path = "/"
}
originalDirector(req)
}
excalidrawOrigin := os.Getenv("EXCALIDRAW_VIEWER_ORIGIN")
if excalidrawOrigin == "" {
excalidrawOrigin = "http://excalidraw-viewer:8080"
}
excalidrawURL, err := url.Parse(excalidrawOrigin)
if err != nil {
log.Fatal(err)
}
excalidrawProxy := httputil.NewSingleHostReverseProxy(excalidrawURL)
excalidrawDirector := excalidrawProxy.Director
excalidrawProxy.Director = func(req *http.Request) {
req.URL.Path = strings.TrimPrefix(req.URL.Path, "/excalidraw")
if req.URL.Path == "" {
req.URL.Path = "/"
}
excalidrawDirector(req)
}
g := &gateway{origin: origin, client: &http.Client{Timeout: 30 * time.Second}, sessions: map[string]gatewaySession{}, codeProxy: proxy, excalidrawProxy: excalidrawProxy}
mux := http.NewServeMux()
mux.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) { w.Write([]byte("ok")) })
mux.HandleFunc("/open", g.open)
mux.HandleFunc("/code/open", g.open)
mux.HandleFunc("/vim/open", g.open)
mux.HandleFunc("/edit", g.edit)
mux.HandleFunc("/save", g.save)
mux.HandleFunc("/code/", g.code)
mux.HandleFunc("/vim/api/session", g.vimSession)
mux.HandleFunc("/vim/api/save", g.vimSave)
vimFiles := http.FileServer(http.Dir("/vimwasm"))
vimHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/vim/" {
data, err := os.ReadFile("/vimwasm/index.html")
if err != nil {
http.Error(w, "vim.wasm frontend is unavailable", http.StatusServiceUnavailable)
return
}
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write(data)
return
}
http.StripPrefix("/vim/", vimFiles).ServeHTTP(w, r)
})
mux.Handle("/vim/", isolationHeaders(vimHandler))
mux.Handle("/excalidraw/", excalidrawHeaders(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
g.excalidrawProxy.ServeHTTP(w, r)
})))
log.Printf("adapter gateway origin=%s listen=:3000", origin)
log.Fatal(http.ListenAndServe(":3000", mux))
}
func excalidrawHeaders(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Security-Policy", "default-src 'self'; script-src 'self' 'unsafe-eval' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; worker-src 'self' blob:; connect-src 'self'; frame-ancestors 'self'; object-src 'none'; base-uri 'none'")
w.Header().Set("X-Content-Type-Options", "nosniff")
w.Header().Set("Referrer-Policy", "no-referrer")
next.ServeHTTP(w, r)
})
}
func isolationHeaders(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cross-Origin-Opener-Policy", "same-origin")
w.Header().Set("Cross-Origin-Embedder-Policy", "require-corp")
w.Header().Set("Cross-Origin-Resource-Policy", "same-origin")
w.Header().Set("Origin-Agent-Cluster", "?1")
next.ServeHTTP(w, r)
})
}
func randomID() string {
b := make([]byte, 24)
_, _ = rand.Read(b)
return hex.EncodeToString(b)
}
func ensureCoderDirectory(root, directory string) error {
relative, err := filepath.Rel(root, directory)
if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
return fmt.Errorf("workspace directory escapes root")
}
current := root
for _, component := range strings.Split(relative, string(filepath.Separator)) {
if component == "" || component == "." {
continue
}
current = filepath.Join(current, component)
if err := os.Mkdir(current, 0700); err != nil && !os.IsExist(err) {
return err
}
if err := os.Chown(current, 1000, 1000); err != nil {
return err
}
}
return nil
}
func (g *gateway) request(method, path, bearer string, input any, output any) error {
var body io.Reader
if input != nil {
data, _ := json.Marshal(input)
body = bytes.NewReader(data)
}
req, err := http.NewRequest(method, g.origin+path, body)
if err != nil {
return err
}
req.Header.Set("Content-Type", "application/json")
if bearer != "" {
req.Header.Set("Authorization", "Bearer "+bearer)
}
res, err := g.client.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode < 200 || res.StatusCode >= 300 {
message, _ := io.ReadAll(io.LimitReader(res.Body, 4096))
return fmt.Errorf("Pages Wiki HTTP %d: %s", res.StatusCode, strings.TrimSpace(string(message)))
}
return json.NewDecoder(res.Body).Decode(output)
}
func (g *gateway) open(w http.ResponseWriter, r *http.Request) {
publicPrefix := strings.TrimRight(strings.TrimSpace(r.Header.Get("X-Forwarded-Prefix")), "/")
ticket := strings.TrimSpace(r.URL.Query().Get("ticket"))
if ticket == "" {
http.Error(w, "ticket is required", 400)
return
}
var exchanged struct {
SessionToken string `json:"session_token"`
PluginID string `json:"plugin_id"`
Filename string `json:"filename"`
ContentType string `json:"content_type"`
ExpiresAtMS int64 `json:"expires_at_ms"`
}
if err := g.request("POST", "/_/api/v1/adapter/session/exchange", "",
map[string]string{"ticket": ticket}, &exchanged); err != nil {
http.Error(w, err.Error(), http.StatusBadGateway)
return
}
var workspaceData struct {
VimSettings json.RawMessage `json:"vim_settings"`
Files []struct {
Path string `json:"path"`
SemanticPath string `json:"semantic_path"`
RevisionUUID string `json:"revision_uuid"`
ContentBase64 string `json:"content_base64"`
} `json:"files"`
}
if err := g.request("GET", "/_/api/v1/adapter/session/workspace", exchanged.SessionToken, nil, &workspaceData); err != nil {
http.Error(w, err.Error(), http.StatusBadGateway)
return
}
id := randomID()
workspace := filepath.Join("/workspaces", id)
if err := os.MkdirAll(workspace, 0700); err != nil {
http.Error(w, err.Error(), 500)
return
}
_ = os.Chown(workspace, 1000, 1000)
files := make(map[string]gatewayFile, len(workspaceData.Files))
filename := "document.txt"
for index, source := range workspaceData.Files {
clean := filepath.Clean(filepath.FromSlash(source.Path))
if clean == "." || filepath.IsAbs(clean) || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
continue
}
data, decodeErr := base64.StdEncoding.DecodeString(source.ContentBase64)
if decodeErr != nil {
http.Error(w, "invalid workspace content", http.StatusBadGateway)
return
}
target := filepath.Join(workspace, clean)
if _, duplicate := files[clean]; duplicate {
http.Error(w, "workspace contains duplicate filenames", http.StatusConflict)
return
}
if err := ensureCoderDirectory(workspace, filepath.Dir(target)); err != nil {
http.Error(w, err.Error(), 500)
return
}
if err := os.WriteFile(target, data, 0600); err != nil {
http.Error(w, err.Error(), 500)
return
}
_ = os.Chown(target, 1000, 1000)
files[clean] = gatewayFile{SemanticPath: source.SemanticPath,
RevisionUUID: source.RevisionUUID, LastContent: source.ContentBase64}
if index == 0 {
filename = clean
}
}
if len(files) == 0 {
http.Error(w, "workspace contains no editable files", http.StatusBadGateway)
return
}
g.mu.Lock()
g.sessions[id] = gatewaySession{Token: exchanged.SessionToken, PluginID: exchanged.PluginID, Filename: filename,
ContentType: exchanged.ContentType, ExpiresAtMS: exchanged.ExpiresAtMS,
Workspace: workspace, Files: files, VimSettings: workspaceData.VimSettings}
g.mu.Unlock()
cookiePath := "/"
if publicPrefix != "" {
cookiePath = publicPrefix + "/"
}
http.SetCookie(w, &http.Cookie{Name: "pageswiki_adapter", Value: id, Path: cookiePath, HttpOnly: true, SameSite: http.SameSiteLaxMode, MaxAge: 8 * 3600})
if exchanged.PluginID == "vim.wasm" {
go g.expire(id)
http.Redirect(w, r, publicPrefix+"/vim/", http.StatusFound)
return
}
go g.watch(id)
http.Redirect(w, r, publicPrefix+"/code/?folder="+url.QueryEscape(workspace), http.StatusFound)
}
func (g *gateway) session(r *http.Request) (gatewaySession, bool) {
cookie, err := r.Cookie("pageswiki_adapter")
if err != nil {
return gatewaySession{}, false
}
g.mu.Lock()
defer g.mu.Unlock()
s, ok := g.sessions[cookie.Value]
if !ok || s.ExpiresAtMS < time.Now().UnixMilli() {
delete(g.sessions, cookie.Value)
return gatewaySession{}, false
}
return s, true
}
var editorTemplate = template.Must(template.New("editor").Parse(`<!doctype html>
<html><head><meta charset="utf-8"><title>{{.Filename}}</title>
<style>html,body,form{height:100%;margin:0}form{display:grid;grid-template-rows:auto 1fr}.bar{padding:.5rem;background:#20242b;color:#eee}textarea{resize:none;border:0;padding:1rem;font:14px/1.5 monospace;background:#11151a;color:#e8e8e8;outline:0}</style></head>
<body><form method="post" action="/save"><div class="bar"><strong>{{.Filename}}</strong> <button type="submit">Save as new Revision</button> {{.Status}}</div><textarea name="content" spellcheck="false">{{.Content}}</textarea></form></body></html>`))
func (g *gateway) edit(w http.ResponseWriter, r *http.Request) {
s, ok := g.session(r)
if !ok {
http.Error(w, "session expired", 401)
return
}
var content struct {
ContentBase64 string `json:"content_base64"`
}
if err := g.request("GET", "/_/api/v1/adapter/session/content", s.Token, nil, &content); err != nil {
http.Error(w, err.Error(), 502)
return
}
data, err := base64.StdEncoding.DecodeString(content.ContentBase64)
if err != nil {
http.Error(w, "invalid content", 502)
return
}
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_ = editorTemplate.Execute(w, map[string]any{"Filename": s.Filename, "Content": string(data), "Status": r.URL.Query().Get("status")})
}
func (g *gateway) save(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", 405)
return
}
s, ok := g.session(r)
if !ok {
http.Error(w, "session expired", 401)
return
}
r.Body = http.MaxBytesReader(w, r.Body, 65<<20)
if err := r.ParseForm(); err != nil {
http.Error(w, err.Error(), 400)
return
}
var output map[string]any
err := g.request("PUT", "/_/api/v1/adapter/session/content", s.Token, map[string]string{
"content_base64": base64.StdEncoding.EncodeToString([]byte(r.FormValue("content"))),
"message": "hosted editor: " + s.Filename,
}, &output)
if err != nil {
http.Error(w, err.Error(), http.StatusConflict)
return
}
http.Redirect(w, r, "/edit?status=saved", http.StatusFound)
}
func (g *gateway) code(w http.ResponseWriter, r *http.Request) {
if _, ok := g.session(r); !ok {
http.Error(w, "session expired", http.StatusUnauthorized)
return
}
g.codeProxy.ServeHTTP(w, r)
}
func (g *gateway) vimSession(w http.ResponseWriter, r *http.Request) {
session, ok := g.session(r)
if !ok || session.PluginID != "vim.wasm" {
http.Error(w, "session expired", http.StatusUnauthorized)
return
}
type vimFile struct {
Path string `json:"path"`
Content string `json:"content"`
}
files := make([]vimFile, 0, len(session.Files))
for relative, tracked := range session.Files {
data, err := base64.StdEncoding.DecodeString(tracked.LastContent)
if err != nil {
continue
}
files = append(files, vimFile{Path: filepath.ToSlash(relative), Content: string(data)})
}
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
_ = json.NewEncoder(w).Encode(map[string]any{"initial": filepath.ToSlash(session.Filename), "files": files, "vim_settings": session.VimSettings})
}
func (g *gateway) vimSave(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPut {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
session, ok := g.session(r)
if !ok || session.PluginID != "vim.wasm" {
http.Error(w, "session expired", http.StatusUnauthorized)
return
}
var input struct {
Path string `json:"path"`
ContentBase64 string `json:"content_base64"`
}
r.Body = http.MaxBytesReader(w, r.Body, 65<<20)
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
http.Error(w, "invalid JSON", http.StatusBadRequest)
return
}
clean := filepath.Clean(filepath.FromSlash(strings.TrimPrefix(input.Path, "/work/")))
tracked, exists := session.Files[clean]
if !exists {
http.Error(w, "file is outside the adapter workspace", http.StatusForbidden)
return
}
var output struct {
RevisionUUID string `json:"revision_uuid"`
}
err := g.request("PUT", "/_/api/v1/adapter/session/content", session.Token,
map[string]string{"content_base64": input.ContentBase64, "path": tracked.SemanticPath,
"revision_uuid": tracked.RevisionUUID, "message": "vim.wasm write: " + clean}, &output)
if err != nil {
http.Error(w, err.Error(), http.StatusConflict)
return
}
cookie, _ := r.Cookie("pageswiki_adapter")
g.mu.Lock()
current, exists := g.sessions[cookie.Value]
if exists {
updated := current.Files[clean]
updated.LastContent = input.ContentBase64
updated.RevisionUUID = output.RevisionUUID
current.Files[clean] = updated
g.sessions[cookie.Value] = current
}
g.mu.Unlock()
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{"revision_uuid": output.RevisionUUID})
}
func (g *gateway) expire(id string) {
g.mu.Lock()
session, ok := g.sessions[id]
g.mu.Unlock()
if !ok {
return
}
delay := time.Until(time.UnixMilli(session.ExpiresAtMS))
if delay > 0 {
timer := time.NewTimer(delay)
defer timer.Stop()
<-timer.C
}
g.mu.Lock()
session, ok = g.sessions[id]
delete(g.sessions, id)
g.mu.Unlock()
if ok {
if err := os.RemoveAll(session.Workspace); err != nil {
log.Printf("remove expired workspace %s: %v", session.Workspace, err)
}
}
}
func (g *gateway) watch(id string) {
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
defer func() {
g.mu.Lock()
session, ok := g.sessions[id]
delete(g.sessions, id)
g.mu.Unlock()
if ok {
if err := os.RemoveAll(session.Workspace); err != nil {
log.Printf("remove expired workspace %s: %v", session.Workspace, err)
}
}
}()
for range ticker.C {
g.mu.Lock()
session, ok := g.sessions[id]
g.mu.Unlock()
if !ok || session.ExpiresAtMS < time.Now().UnixMilli() {
return
}
for relative, tracked := range session.Files {
data, err := os.ReadFile(filepath.Join(session.Workspace, relative))
if err != nil {
continue
}
encoded := base64.StdEncoding.EncodeToString(data)
if encoded == tracked.LastContent {
continue
}
var output struct {
RevisionUUID string `json:"revision_uuid"`
}
err = g.request("PUT", "/_/api/v1/adapter/session/content", session.Token,
map[string]string{"content_base64": encoded, "path": tracked.SemanticPath,
"revision_uuid": tracked.RevisionUUID, "message": "code-server autosave: " + relative}, &output)
g.mu.Lock()
current, exists := g.sessions[id]
if exists {
currentFile := current.Files[relative]
if err == nil {
currentFile.LastContent = encoded
currentFile.RevisionUUID = output.RevisionUUID
current.Files[relative] = currentFile
current.LastError = ""
} else {
current.LastError = err.Error()
}
g.sessions[id] = current
}
g.mu.Unlock()
}
}
}
+254
View File
@@ -0,0 +1,254 @@
package main
import (
"bytes"
"crypto/ed25519"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"os"
"path/filepath"
"strings"
"time"
"pageswiki/internal/store"
)
type externalCampusEnrollment struct {
FQDN string
Token string
HTTP bool
NoDefaultCampus bool
}
type campusEnrollmentSnapshot struct {
Campus store.Campus
Instance store.FederationInstance
Domains []store.Domain
Manifest store.SignedCampusManifest `json:"manifest"`
}
func parseExternalCampusEnrollment(args []string) (*externalCampusEnrollment, error) {
if len(args) == 0 {
return nil, nil
}
noDefaultCampus := false
filtered := make([]string, 0, len(args))
for _, arg := range args {
if arg == "--no-default-campus" {
if noDefaultCampus {
return nil, errors.New("--no-default-campus was specified twice")
}
noDefaultCampus = true
continue
}
filtered = append(filtered, arg)
}
if len(filtered) != 3 ||
(filtered[0] != "--add-external-campus" &&
filtered[0] != "--add-external-campus-http") {
return nil, errors.New(
"usage: pageswiki [--no-default-campus] " +
"[--add-external-campus FQDN TOKEN | " +
"--add-external-campus-http FQDN TOKEN]",
)
}
return &externalCampusEnrollment{
FQDN: strings.TrimSpace(filtered[1]),
Token: strings.TrimSpace(filtered[2]),
HTTP: filtered[0] == "--add-external-campus-http",
NoDefaultCampus: noDefaultCampus,
}, nil
}
func enrollExternalCampus(
dataDir string,
st *store.Store,
enrollment *externalCampusEnrollment,
) error {
if enrollment == nil {
return nil
}
instanceFQDN := strings.TrimSpace(os.Getenv("PAGESWIKI_INSTANCE_FQDN"))
if instanceFQDN == "" {
return errors.New(
"PAGESWIKI_INSTANCE_FQDN is required for external Campus enrollment",
)
}
snapshot, scheme, err := fetchCampusSnapshot(
dataDir,
enrollment,
instanceFQDN,
)
if err != nil {
return err
}
if err := applyEnrollmentSnapshot(st, snapshot, "", instanceFQDN, scheme); err != nil {
return err
}
if err := saveCampusEnrollment(
dataDir,
snapshot.Campus.UUID,
enrollment,
); err != nil {
return err
}
if enrollment.NoDefaultCampus {
_, err = st.RemoveUnusedBootstrapCampus()
}
return err
}
func applyEnrollmentSnapshot(st *store.Store, snapshot *campusEnrollmentSnapshot, expectedCampusUUID, instanceFQDN, scheme string) error {
if snapshot.Manifest.SchemaVersion != 0 {
return st.ApplySignedManagedCampusManifest(snapshot.Manifest, expectedCampusUUID, instanceFQDN, scheme)
}
// Transitional compatibility for pre-manifest controllers. New controllers
// always emit a signed manifest; this branch can be removed after upgrades.
return st.ApplyManagedCampusSnapshot(snapshot.Campus, snapshot.Domains, instanceFQDN, scheme)
}
func fetchCampusSnapshot(
dataDir string,
enrollment *externalCampusEnrollment,
instanceFQDN string,
) (*campusEnrollmentSnapshot, string, error) {
privateKey, fingerprint, err := ensureInstanceIdentity(dataDir)
if err != nil {
return nil, "", err
}
payload, err := json.Marshal(map[string]any{
"manifest_version": 2,
"capability_signature": base64.RawStdEncoding.EncodeToString(ed25519.Sign(privateKey, []byte(store.FederationCapabilityMessage(instanceFQDN, enrollment.Token)))),
"fqdn": instanceFQDN,
"fingerprint": fingerprint,
"public_key": base64.RawStdEncoding.EncodeToString(
privateKey.Public().(ed25519.PublicKey),
),
"signature": base64.RawStdEncoding.EncodeToString(
ed25519.Sign(
privateKey,
[]byte(instanceFQDN+"\n"+enrollment.Token),
),
),
})
if err != nil {
return nil, "", err
}
scheme := "https"
if enrollment.HTTP {
scheme = "http"
}
endpoint := fmt.Sprintf(
"%s://%s/_/api/v1/federation/enroll",
scheme,
enrollment.FQDN,
)
request, err := http.NewRequest(
http.MethodPost,
endpoint,
bytes.NewReader(payload),
)
if err != nil {
return nil, "", err
}
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Authorization", "Bearer "+enrollment.Token)
client := &http.Client{Timeout: 20 * time.Second}
response, err := client.Do(request)
if err != nil {
return nil, "", err
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
message, _ := io.ReadAll(io.LimitReader(response.Body, 4<<10))
detail := strings.TrimSpace(string(message))
if detail != "" {
return nil, "", fmt.Errorf(
"Campus controller enrollment failed: %s: %s",
response.Status,
detail,
)
}
return nil, "", fmt.Errorf(
"Campus controller enrollment failed: %s",
response.Status,
)
}
var snapshot campusEnrollmentSnapshot
if err := json.NewDecoder(response.Body).Decode(&snapshot); err != nil {
return nil, "", err
}
return &snapshot, scheme, nil
}
func saveCampusEnrollment(
dataDir string,
campusUUID string,
enrollment *externalCampusEnrollment,
) error {
tokenDir := filepath.Join(dataDir, "federation")
if err := os.MkdirAll(tokenDir, 0700); err != nil {
return err
}
tokenPath := filepath.Join(tokenDir, campusUUID+".token")
if err := os.WriteFile(
tokenPath,
[]byte(enrollment.Token+"\n"),
0600,
); err != nil {
return err
}
if enrollment.NoDefaultCampus {
markerPath := filepath.Join(
tokenDir,
campusUUID+".no-default-campus",
)
if err := os.WriteFile(markerPath, nil, 0600); err != nil {
return err
}
}
scheme := "https"
if enrollment.HTTP {
scheme = "http"
}
endpointPath := filepath.Join(tokenDir, campusUUID+".endpoint")
return os.WriteFile(
endpointPath,
[]byte(scheme+"://"+enrollment.FQDN+"\n"),
0600,
)
}
func ensureInstanceIdentity(
dataDir string,
) (ed25519.PrivateKey, string, error) {
keyPath := filepath.Join(dataDir, "instance-ed25519.key")
privateKey, err := os.ReadFile(keyPath)
if errors.Is(err, os.ErrNotExist) {
_, generated, generateErr := ed25519.GenerateKey(rand.Reader)
if generateErr != nil {
return nil, "", generateErr
}
if writeErr := os.WriteFile(keyPath, generated, 0600); writeErr != nil {
return nil, "", writeErr
}
privateKey = generated
} else if err != nil {
return nil, "", err
}
if len(privateKey) != ed25519.PrivateKeySize {
return nil, "", errors.New("invalid instance Ed25519 private key")
}
publicKey := ed25519.PrivateKey(privateKey).Public().(ed25519.PublicKey)
sum := sha256.Sum256(publicKey)
return ed25519.PrivateKey(privateKey),
"sha256:" + hex.EncodeToString(sum[:]),
nil
}
+80
View File
@@ -0,0 +1,80 @@
package main
import "testing"
func TestExternalCampusEnrollmentArguments(t *testing.T) {
enrollment, err := parseExternalCampusEnrollment([]string{
"--add-external-campus",
"campus.example.test",
"secret-token",
})
if err != nil {
t.Fatal(err)
}
if enrollment.FQDN != "campus.example.test" ||
enrollment.Token != "secret-token" {
t.Fatalf("enrollment = %#v", enrollment)
}
}
func TestExternalCampusHTTPEnrollmentArguments(t *testing.T) {
enrollment, err := parseExternalCampusEnrollment([]string{
"--add-external-campus-http",
"campus.internal.test",
"secret-token",
})
if err != nil {
t.Fatal(err)
}
if !enrollment.HTTP {
t.Fatal("HTTP enrollment did not select HTTP transport")
}
}
func TestExternalCampusNoDefaultCampusArgument(t *testing.T) {
for _, args := range [][]string{
{
"--no-default-campus",
"--add-external-campus",
"campus.example.test",
"secret-token",
},
{
"--add-external-campus-http",
"campus.internal.test",
"secret-token",
"--no-default-campus",
},
} {
enrollment, err := parseExternalCampusEnrollment(args)
if err != nil {
t.Fatal(err)
}
if !enrollment.NoDefaultCampus {
t.Fatalf("NoDefaultCampus is false for %#v", args)
}
}
}
func TestNoDefaultCampusRequiresExternalCampus(t *testing.T) {
if _, err := parseExternalCampusEnrollment([]string{
"--no-default-campus",
}); err == nil {
t.Fatal("--no-default-campus without enrollment was accepted")
}
}
func TestInstanceFingerprintIsPersistent(t *testing.T) {
dataDir := t.TempDir()
_, first, err := ensureInstanceIdentity(dataDir)
if err != nil {
t.Fatal(err)
}
_, second, err := ensureInstanceIdentity(dataDir)
if err != nil {
t.Fatal(err)
}
if first != second {
t.Fatalf("fingerprints differ: %q, %q", first, second)
}
}
+119
View File
@@ -0,0 +1,119 @@
package main
import (
"errors"
"log"
"net/url"
"os"
"path/filepath"
"strings"
"time"
"pageswiki/internal/store"
)
const managedCampusReconcileInterval = 5 * time.Second
func startManagedCampusReconciler(dataDir string, st *store.Store) {
instanceFQDN := strings.TrimSpace(os.Getenv("PAGESWIKI_INSTANCE_FQDN"))
if instanceFQDN == "" {
return
}
go func() {
ticker := time.NewTicker(managedCampusReconcileInterval)
defer ticker.Stop()
for range ticker.C {
reconcileManagedCampuses(dataDir, st, instanceFQDN)
}
}()
}
func reconcileManagedCampuses(
dataDir string,
st *store.Store,
instanceFQDN string,
) {
campuses, err := st.ListCampuses()
if err != nil {
log.Printf("managed Campus reconciliation: %v", err)
return
}
for _, campus := range campuses {
if campus.AuthorityMode != "managed" || !campus.Enabled {
continue
}
if err := reconcileManagedCampus(
dataDir,
st,
campus,
instanceFQDN,
); err != nil {
_ = st.RecordCampusContact(campus.UUID, err.Error())
if campus.LastContactError != err.Error() {
log.Printf(
"managed Campus %s reconciliation failed: %v",
campus.FQDN,
err,
)
}
}
}
}
func reconcileManagedCampus(
dataDir string,
st *store.Store,
campus store.Campus,
instanceFQDN string,
) error {
tokenDir := filepath.Join(dataDir, "federation")
token, err := os.ReadFile(
filepath.Join(tokenDir, campus.UUID+".token"),
)
if err != nil {
return err
}
controllerAddress := campus.Transport + "://" + campus.FQDN
endpoint, err := os.ReadFile(
filepath.Join(tokenDir, campus.UUID+".endpoint"),
)
if err == nil {
controllerAddress = strings.TrimSpace(string(endpoint))
} else if !errors.Is(err, os.ErrNotExist) {
return err
}
parsed, err := url.Parse(controllerAddress)
if err != nil || parsed.Host == "" {
return errors.New("invalid saved Campus controller endpoint")
}
enrollment := &externalCampusEnrollment{
FQDN: parsed.Host,
Token: strings.TrimSpace(string(token)),
HTTP: parsed.Scheme == "http",
}
snapshot, scheme, err := fetchCampusSnapshot(
dataDir,
enrollment,
instanceFQDN,
)
if err != nil {
return err
}
if snapshot.Campus.UUID != campus.UUID && snapshot.Manifest.Campus.UUID != campus.UUID {
return errors.New("Campus controller identity changed")
}
if err := applyEnrollmentSnapshot(st, snapshot, campus.UUID, instanceFQDN, scheme); err != nil {
return err
}
markerPath := filepath.Join(
tokenDir,
campus.UUID+".no-default-campus",
)
if _, err := os.Stat(markerPath); err == nil {
_, err = st.RemoveUnusedBootstrapCampus()
return err
} else if !errors.Is(err, os.ErrNotExist) {
return err
}
return nil
}
+118
View File
@@ -0,0 +1,118 @@
package main
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"pageswiki/internal/db"
"pageswiki/internal/store"
)
func TestManagedCampusReconciliationDeploysAssignedDomain(t *testing.T) {
dataDir := t.TempDir()
database, err := db.Open(dataDir + "/pages.db")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = database.Close() })
if err := db.Migrate(database); err != nil {
t.Fatal(err)
}
st := store.New(database)
if err := st.EnsureConfigTable(); err != nil {
t.Fatal(err)
}
const (
campusUUID = "1140999c-b690-4c38-850d-8e04572e489e"
domainUUID = "2251000d-c7a1-4d49-961e-9f15683f590f"
instanceFQDN = "node.example.test"
)
campus := store.Campus{
UUID: campusUUID,
Name: "external",
Title: "External Campus",
DefaultLang: "en",
AuthorityMode: "controller",
FQDN: "campus.example.test",
Enabled: true,
}
domain := store.Domain{
UUID: domainUUID,
Name: "deployed",
Title: "Deployed Domain",
Domain: "deployed.example.test",
Enabled: true,
CampusUUID: campusUUID,
Placement: "remote",
InstanceFQDN: instanceFQDN,
InstanceFingerprint: "sha256:test",
}
controller := httptest.NewServer(http.HandlerFunc(
func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/_/api/v1/federation/enroll" {
http.NotFound(w, r)
return
}
_ = json.NewEncoder(w).Encode(map[string]any{
"campus": campus,
"domains": []store.Domain{domain},
})
},
))
t.Cleanup(controller.Close)
if err := st.ApplyManagedCampusSnapshot(
campus,
nil,
instanceFQDN,
"http",
); err != nil {
t.Fatal(err)
}
enrollment := &externalCampusEnrollment{
FQDN: strings.TrimPrefix(controller.URL, "http://"),
Token: "test-token",
HTTP: true,
NoDefaultCampus: true,
}
if err := saveCampusEnrollment(
dataDir,
campusUUID,
enrollment,
); err != nil {
t.Fatal(err)
}
managed, err := st.GetCampusByUUID(campusUUID)
if err != nil {
t.Fatal(err)
}
if err := reconcileManagedCampus(
dataDir,
st,
*managed,
instanceFQDN,
); err != nil {
t.Fatal(err)
}
deployed, err := st.GetDomainByUUID(domainUUID)
if err != nil {
t.Fatal(err)
}
if deployed.Placement != "local" || !deployed.Enabled {
t.Fatalf("deployed Domain = %#v", deployed)
}
campuses, err := st.ListCampuses()
if err != nil {
t.Fatal(err)
}
if len(campuses) != 1 ||
campuses[0].UUID != campusUUID ||
campuses[0].AuthorityMode != "managed" {
t.Fatalf("Campuses after reconciliation = %#v", campuses)
}
}
+25 -3
View File
@@ -3,13 +3,18 @@ package main
import (
"log"
"os"
"path/filepath"
"pageswiki/internal/db"
"pageswiki/internal/server"
"pageswiki/internal/store"
"path/filepath"
)
func main() {
enrollment, err := parseExternalCampusEnrollment(os.Args[1:])
if err != nil {
log.Fatal(err)
}
dataDir :=
os.Getenv(
@@ -20,7 +25,7 @@ func main() {
dataDir = "./data"
}
err := os.MkdirAll(
err = os.MkdirAll(
dataDir,
0755,
)
@@ -53,7 +58,20 @@ func main() {
log.Fatal(err)
}
st := store.New(database)
documentRoot, err :=
store.MigrateLegacyDocumentRoot(
dataDir,
)
if err != nil {
log.Fatal(err)
}
st :=
store.NewWithDocumentRoot(
database,
documentRoot,
)
err = st.EnsureConfigTable()
@@ -66,6 +84,10 @@ func main() {
if err != nil {
log.Fatal(err)
}
if err := enrollExternalCampus(dataDir, st, enrollment); err != nil {
log.Fatal(err)
}
startManagedCampusReconciler(dataDir, st)
srv := server.New(st)
+1636
View File
File diff suppressed because it is too large. Load diff
+47
View File
@@ -0,0 +1,47 @@
import importlib.util
from pathlib import Path
import unittest
SCRIPT = Path(__file__).with_name("pageswiki-cli")
SPEC = importlib.util.spec_from_file_location("pageswiki_cli", SCRIPT)
if SPEC is None or SPEC.loader is None:
from importlib.machinery import SourceFileLoader
SPEC = importlib.util.spec_from_loader(
"pageswiki_cli",
SourceFileLoader("pageswiki_cli", str(SCRIPT)),
)
assert SPEC is not None and SPEC.loader is not None
pageswiki_cli = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(pageswiki_cli)
class ContentTypeDetectionTest(unittest.TestCase):
def test_extensionless_shell(self) -> None:
content_type = pageswiki_cli.detect_content_type(
b"#!/usr/bin/env bash\necho hello\n",
)
self.assertEqual(content_type, "application/x-sh; charset=utf-8")
def test_extensionless_utf8_text(self) -> None:
content_type = pageswiki_cli.detect_content_type(
"拡張子なしの文書\n".encode(),
)
self.assertEqual(content_type, "text/plain; charset=utf-8")
def test_magic_number_wins_over_text_analysis(self) -> None:
content_type = pageswiki_cli.detect_content_type(
b"%PDF-1.7\nsample",
)
self.assertEqual(content_type, "application/pdf")
def test_shift_jis_text(self) -> None:
content_type = pageswiki_cli.detect_content_type(
"日本語の文書\n".encode("shift_jis"),
)
self.assertEqual(content_type, "text/plain; charset=shift_jis")
if __name__ == "__main__":
unittest.main()
+43
View File
@@ -0,0 +1,43 @@
import runpy
import sqlite3
import tempfile
import unittest
from pathlib import Path
CLI = runpy.run_path(str(Path(__file__).with_name("pageswiki-cli")))["PagesWikiCLI"]
class AssetMetadataTest(unittest.TestCase):
def test_head_metadata_and_history_follow_cli_uploads(self):
with tempfile.TemporaryDirectory() as directory:
cli = CLI.__new__(CLI)
cli.documents = Path(directory) / "documents"
cli.domain_uuid = "test-domain"
cli.db = sqlite3.connect(":memory:")
self.addCleanup(cli.db.close)
cli.db.row_factory = sqlite3.Row
cli.db.executescript("""
CREATE TABLE objects(uuid TEXT PRIMARY KEY,kind TEXT,created_at INTEGER);
CREATE TABLE assets(domain_uuid TEXT,address TEXT,object_uuid TEXT,
head_document_hash TEXT,content_type TEXT,filename TEXT,size_bytes INTEGER,
created_at_ms INTEGER,updated_at_ms INTEGER,PRIMARY KEY(domain_uuid,address));
""")
address = "asset:image:logo"
payload = b"\x89PNG\r\n\x1a\nfixture"
self.assertEqual(cli.put_asset(address, payload, "logo.png"), "updated")
self.assertEqual(cli.put_asset(address, payload, "logo.png"), "skipped")
self.assertEqual(cli.put_asset(address, payload, "renamed.png"), "updated")
row = cli.db.execute("SELECT * FROM assets").fetchone()
self.assertEqual(row["content_type"], "image/png")
self.assertEqual(row["filename"], "renamed.png")
self.assertEqual(row["size_bytes"], len(payload))
self.assertEqual(cli.document_path(row["head_document_hash"]).read_bytes(), payload)
history = cli.db.execute("SELECT * FROM asset_head_history ORDER BY id").fetchall()
self.assertEqual(len(history), 2)
self.assertEqual(history[-1]["document_hash"], row["head_document_hash"])
self.assertEqual(history[-1]["filename"], "renamed.png")
if __name__ == "__main__":
unittest.main()
+110 -11
View File
@@ -1,20 +1,119 @@
services:
nginx:
container_name: pageswiki-proxy
image: nginx:1.27-alpine
restart: unless-stopped
ports:
- "8080:80"
volumes:
- ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
- app
app:
container_name: pageswiki
build: .
image: pageswiki-app
networks:
default:
aliases:
- extpages.anya.jp
volumes:
- ./data:/data
ports:
- "3000:3000"
environment:
PAGESWIKI_DATA_DIR: /data
KROKI_URL: http://kroki:8000
PAGESWIKI_ADAPTER_GATEWAY_ORIGIN: http://adaptor-gateway:3000
extra_hosts:
- "id.anya.jp:172.18.0.10"
healthcheck:
test: ["CMD", "wget", "-q", "-O", "-", "http://localhost:3000/health"]
interval: 2s
timeout: 1s
retries: 15
restart: unless-stopped
app2:
container_name: pageswiki-ext
image: pageswiki-app
command: >
/pageswiki --no-default-campus --add-external-campus-http extpages.anya.jp:3000 ${PAGESWIKI_EXTERNAL_CAMPUS_TOKEN:?Set PAGESWIKI_EXTERNAL_CAMPUS_TOKEN in .env}
volumes:
- ./data2:/data
ports:
- "3001:3000"
environment:
PAGESWIKI_INSTANCE_FQDN: ext-node-pages.anya.jp
PAGESWIKI_DATA_DIR: /data
KROKI_URL: http://kroki:8000
extra_hosts:
- "id.anya.jp:172.18.0.10"
depends_on:
app:
condition: service_healthy
restart: unless-stopped
adaptor-gateway:
container_name: pageswiki-adaptor-gateway
build:
context: .
dockerfile: Dockerfile.adapter-gateway
environment:
PAGESWIKI_ORIGIN: http://app:3000
CODE_SERVER_ORIGIN: http://code-server:8080
EXCALIDRAW_VIEWER_ORIGIN: http://excalidraw-viewer:8080
volumes:
- adapter-workspaces:/workspaces
expose:
- "3000"
depends_on:
app:
condition: service_healthy
code-server:
condition: service_started
excalidraw-viewer:
condition: service_healthy
restart: unless-stopped
code-server:
container_name: pageswiki-code-server
image: codercom/code-server:latest
command:
- --bind-addr
- 0.0.0.0:8080
- --auth
- none
- --disable-telemetry
- --disable-proxy
- --disable-getting-started-override
- /workspaces
expose:
- "8080"
volumes:
- adapter-workspaces:/workspaces
restart: unless-stopped
excalidraw-viewer:
container_name: pageswiki-excalidraw-viewer
build:
context: .
dockerfile: Dockerfile.excalidraw-viewer
expose:
- "8080"
healthcheck:
test: ["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8080/health"]
interval: 5s
timeout: 2s
retries: 12
restart: unless-stopped
kroki:
image: yuzutech/kroki
environment:
KROKI_MERMAID_HOST: kroki-mermaid
KROKI_MERMAID_PORT: 8002
restart: unless-stopped
depends_on:
- kroki-mermaid
kroki-mermaid:
image: yuzutech/kroki-mermaid
restart: unless-stopped
expose:
- "8002"
volumes:
adapter-workspaces:
networks:
default:
ipam:
config:
- subnet: 172.23.0.0/27
+58
View File
@@ -0,0 +1,58 @@
# PagesWiki design documentation
## Current reading order
The reorganized Japanese handbook is [ja/index.md](ja/index.md), published under
`https://pages.anya.jp/lab/pageswiki-dev/`. It separates implemented slices,
proposals, unresolved decisions and delivery gates. Its chapter identifiers are
language-neutral; existing English source documents remain here for traceability
and future aligned translations, not as automatically current English editions.
- Concepts and boundaries: chapters 1–6.
- Existing product and runtime: chapters 7–11.
- Organizer / task / calendar / RSS / mail / HTML editing proposals: chapters 12–17.
- Operations, i18n, ordered work, decisions and sources: chapters 18–22.
- [Source-to-chapter inventory](ja/sources.md).
- [Decision and inconsistency register](ja/decisions.md).
## Document roles
`arch.md`, `address-model.md`, `access-model.md`, `auth.md` and `i18n-delivery.md`
include original conceptual drafts. Detailed topic documents describe contracts
and implementation slices. `implementation-status.md` contains dated progress;
older paragraphs are historical and may be superseded. The roadmap is a task
inventory; the execution ledger is verification/deployment history, not a blanket
feature-completeness claim.
For new work, update the relevant chapter and detailed contract together. Keep
stable identity, authorization and bounded processing constraints. Do not convert
design proposals into active features or public grants merely by documenting them.
## Publication
Japanese Markdown under `ja/` is the editing source. The documentation export
tool renders canonical HTML with the application's Markdown renderer, validates
chapter links, and emits a manifest. Upload through the trusted data CLI with an
explicit Domain and `PAGESWIKI_LANG=ja`; no authentication/publication policy is
changed. Record resulting Page/Revision identities separately from source text.
English publication is deferred until an aligned translation and language UI
are ready. Never overwrite Japanese with English at language `und`.
Generate a fresh, empty staging directory, then run:
```sh
go run ./tools/design-export -out /tmp/pageswiki-design-staging
go test ./tools/design-export
```
The tool does not access the database or network. Review `manifest.json`, check
destination collisions, and select the correct database/Domain explicitly before
using `data/pageswiki-cli put` for each rendered HTML file and manifest Path.
The index maps to `/lab/pageswiki-dev`, not `/lab/pageswiki-dev/index`.
Do not blindly replace existing Wiki edits on a later publication: compare the
recorded Revision UUID/hash with the current head and resolve divergence first.
The initial upload receipt is [publication-ja-2026-09-19.json](publication-ja-2026-09-19.json).
All 23 canonical payloads were read back and compared. Source hashes and stored
Page/Revision identities support later language alignment. Anonymous HTTPS access
still redirects to login; this upload did not change public access settings.
+665
View File
@@ -0,0 +1,665 @@
# Access Model draft
## Goal
Separate:
```text
knowledge navigation
projection rendering
editing surfaces
object retrieval
native execution
```
into independent runtime layers.
The system treats:
```
content != rendering != editor != storage
```
as a core architectural principle.
# Core Principle
Pages Wiki does NOT treat editors as canonical reality.
Editors are:
```text
authoring projections
```
onto canonical semantic object structures.
Canonical storage is:
```text
DOM/object graph centered
```
depending on object class.
# High-Level Access Architecture
```mermaid
graph TD
KA[Knowledge Access]
PA[Projection Access]
EA[Editing Access]
OA[Object Access]
NA[Native Access]
KA --> PA
PA --> EA
PA --> OA
EA --> OA
PA --> NA
EA --> NA
```
* * *
# 1. Knowledge Access
## Purpose
Semantic navigation for humans.
# Example
```text
/research/network/bgp
/dev/api/auth
/hr/onboarding
```
# Responsibilities
- semantic routing
- hierarchy traversal
- language negotiation
- capability evaluation
- object resolution
# Output
Usually:
```text
rendered semantic projection
```
# Resolution Pipeline
```text
path
↓
uuid
↓
revision
↓
projection
```
# Important Principle
Knowledge access is:
```text
human semantic navigation
```
NOT raw object retrieval.
# 2. Projection Access
## Purpose
Interpret semantic objects into runtime surfaces.
# Example
```text
/_/view/flow/uuid:abcd
/_/view/slides/uuid:abcd
/_/view/sheet/uuid:abcd
/_/view/print/uuid:abcd
/_/view/canvas/uuid:abcd
```
# Projection Examples
| Projection | Meaning |
| --- | --- |
| `flow` | Flowing article |
| `slides` | Staged presentation |
| `print` | Printable layout |
| `sheet` | Spreadsheet runtime |
| `canvas` | Whiteboard/canvas |
| `topology` | Graph topology |
| `preview` | Lightweight rendering |
# Important Principle
Projection is:
```text
runtime interpretation
```
NOT canonical storage.
# Same Object, Multiple Projections
```mermaid
graph TD
OBJ[Semantic Object]
FLOW[Flow Projection]
SLIDE[Slides Projection]
PRINT[Print Projection]
SHEET[Sheet Projection]
OBJ --> FLOW
OBJ --> SLIDE
OBJ --> PRINT
OBJ --> SHEET
```
* * *
# 3. Editing Access
## Purpose
Provide authoring surfaces.
* * *
# Important Principle
Editors are:
```text
projection-specific authoring surfaces
```
NOT canonical storage owners.
* * *
# Editor Pipeline
```mermaid
graph TD
EDITOR[Editor]
AST[Semantic Object Graph]
REV[Revision Snapshot]
EDITOR --> AST
AST --> REV
```
* * *
# Supported Editors
| Editor | Purpose |
| --- | --- |
| Markdown | Lightweight flow editing |
| WYSIWYG | Visual article editing |
| Raw HTML | Direct DOM editing |
| Slide Editor | Presentation authoring |
| Sheet Editor | Spreadsheet runtime editing |
| Whiteboard Editor | Canvas editing |
| DrawIO-like Editor | Topology editing |
* * *
# Important Principle
All editors ultimately produce:
```text
semantic object graph
```
or:
```text
canonical DOM representation
```
depending on object class.
* * *
# Editor Negotiation
Runtime selects editor based on:
- object class
- supported projection types
- runtime capabilities
- user preferences
- available native integrations
* * *
# Example
```text
HTML article
```
Available editors:
- Markdown
- WYSIWYG
- Raw HTML
* * *
# Example
```text
Presentation object
```
Available editors:
- Slide editor
- Raw DOM editor
* * *
# Example
```text
Spreadsheet object
```
Available editors:
- Sheet runtime editor
- Native Excel integration
* * *
# 4. Object Access
## Purpose
Raw immutable object retrieval.
* * *
# Example
```text
/_/obj/sha256:abcd
```
* * *
# Typical Objects
- PDF
- PPTX
- XLSX
- PNG
- SVG
- JS
- CSS
- DrawIO payload
- Excalidraw payload
* * *
# Important Principle
Object access is:
```text
transport/storage retrieval
```
NOT semantic navigation.
* * *
# Object Access Pipeline
```mermaid
graph TD
OBJREF[Object Reference]
FETCH[Object Fetch]
CACHE[Cache/CDN]
RETURN[Runtime Consumer]
OBJREF --> FETCH
FETCH --> CACHE
CACHE --> RETURN
```
* * *
# Important Principle
Object retrieval supports:
- deduplication
- CDN caching
- immutable references
- snapshot reproducibility
- derived object generation
* * *
# 5. Native Access
## Purpose
Bridge semantic objects into local/native applications.
> Implementation status: TODO. The current integration-adapter runtime only
> permits hosted HTTP(S) viewers and editors. Direct executable launch requires
> a separately designed local helper, temporary workspace, credential store,
> executable allowlist, conflict detection, and Revision write-back protocol.
* * *
# Example
| Semantic Link | Native Projection |
| --- | --- |
| `teams.office.com` | `msteams://` |
| `mailto:` | Mail client |
| `tel:` | Dialer |
| `vscode://` | VS Code |
| `figma://` | Figma |
| `slack://` | Slack |
* * *
# Native Resolution Pipeline
```mermaid
graph TD
LINK[Semantic Link]
RES[Resolver]
NATIVE[Native Handler]
WEB[Web Fallback]
LINK --> RES
RES --> NATIVE
RES --> WEB
```
* * *
# Important Principle
Links represent:
```text
semantic execution intent
```
NOT fixed transport mechanisms.
* * *
# Runtime chooses:
- native app
- browser fallback
- embedded projection
- external mounted surface
depending on environment.
* * *
# 6. Workspace Plane vs Revision Plane
## Workspace Plane
Mutable editing world.
Contains:
- path
- alias
- asset
- live editors
* * *
# Revision Plane
Immutable historical world.
Contains:
- revision
- sha256 snapshots
- derived projections
* * *
# Important Principle
Editors operate on:
```text
workspace objects
```
Revisions store:
```text
immutable semantic snapshots
```
* * *
# 7. Canonical Storage Principle
Canonical storage depends on object class.
* * *
# Flow Articles
Canonical form:
```text
HTML DOM
```
* * *
# Presentation Objects
Canonical form:
```text
presentation object graph
```
Projected into:
- SVG sections
- HTML slides
- print layouts
* * *
# Spreadsheet Objects
Canonical form:
```text
structured semantic table graph
```
Projected into:
- HTML tables
- spreadsheet runtime
- CSV
- print layouts
* * *
# Canvas/Whiteboard Objects
Canonical form:
```text
spatial object graph
```
Projected into:
- SVG
- interactive canvas
- thumbnails
* * *
# Important Principle
Projection-specific formats are:
```text
runtime surfaces
```
NOT canonical storage truth.
* * *
# 8. Embedded Object Model
Embedded objects may be:
| Type | Meaning |
| --- | --- |
| Inline | Embedded payload |
| Linked | Immutable external object |
| Mounted | Live external application |
| Derived | Generated projection |
| Lazy | Runtime-fetched object |
* * *
# Example
```html
<embedded-object
kind="drawio"
immutable-ref="sha256:abcd"
></embedded-object>
```
* * *
# Important Principle
Large payloads should generally use:
```text
external immutable object references
```
instead of giant inline blobs.
* * *
# 9. Semantic Link Model
Semantic links may resolve into:
- knowledge paths
- projections
- native applications
- external services
- embedded runtimes
* * *
# Example
```text
/research/network/bgp
```
may contain:
```text
teams://
mailto:
vscode://
figma://
tel:
```
runtime-aware semantic links.
* * *
# 10. Final Architectural Direction
Pages Wiki evolves toward:
```text
semantic knowledge runtime environment
```
rather than:
```text
filesystem-oriented wiki
```
* * *
# Conceptual Summary
| Layer | Responsibility |
| --- | --- |
| Knowledge Access | Semantic navigation |
| Projection Access | Runtime interpretation |
| Editing Access | Authoring surfaces |
| Object Access | Immutable retrieval |
| Native Access | Local runtime execution |
* * *
# Final Principle
Pages Wiki separates:
```text
meaning
identity
projection
editing
storage
runtime execution
```
into independent architectural planes.
+644
View File
@@ -0,0 +1,644 @@
# Address Model Draft
## Goal
Separate:
```text
identity
reachability
semantic meaning
projection
mutability
```
into independent address layers.
The addressing model is designed to support:
- semantic navigation
- immutable revisions
- mutable editing workspaces
- object storage
- projection rendering
- delegated sharing
- graph-capable knowledge topology
## Core Principle
```text
Address != Meaning
```
Addresses are:
```text
reachable locators
```
NOT semantic meaning themselves.
* * *
# Address Layer Overview
| Scheme | Purpose | Mutable | Human-oriented |
| --- | --- | --- | --- |
| `path:` | Semantic navigation | yes | yes |
| `uuid:` | Stable Page/Object identity | no | partially |
| `rev:` | Immutable historical snapshot | no | no |
| `sha256:` | Immutable content identity | no | no |
| `asset:` | Mutable editable workspace | yes | partially |
| `alias:` | Semantic pointer | yes | yes |
| `share:` | Delegated capability projection | caveat-bound | yes |
| `derived:` | Generated object | preferably no | no |
| `external:` | Foreign mounted object | provider-defined | partially |
* * *
# 1. path:
## Purpose
Human semantic routing namespace.
* * *
# Example
```text
/research/network/bgp
/dev/api/auth
/hr/onboarding
```
* * *
# Properties
Property Value mutable yes human-readable yes semantic yes canonical identity no
* * *
# Important Principle
Paths are:
```text
semantic navigation surfaces
```
NOT canonical object identities.
* * *
# Resolution Flow
```text
path
↓
uuid
↓
revision
↓
projection
```
* * *
# 2. uuid:
## Purpose
Stable semantic object identity.
* * *
# Example
```text
uuid:550e8400-e29b-41d4-a716-446655440000
```
* * *
# Properties
Property Value mutable no semantic no canonical identity yes stable yes
* * *
# Important Principle
UUIDs are:
```text
opaque reachable locators
```
NOT semantic meaning.
* * *
# UUID Targets
UUID may identify:
- HTML document object
- PDF semantic object
- Spreadsheet object
- DrawIO semantic object
- Presentation object
- Embedded semantic object
* * *
# Important Principle
UUID does NOT imply rendering format.
Projection decides interpretation.
* * *
# 3. rev:
## Purpose
Immutable historical semantic snapshot.
* * *
# Example
```text
rev:018f6b5d...
```
* * *
# Properties
Property Value immutable yes historical yes reproducible yes
* * *
# Revision Responsibilities
A revision freezes:
- HTML structure
- embedded object references
- semantic state
- projection state
A Revision has its own UUID. Immutable payload identity is represented
separately by `sha256:`. A Revision record links a Page UUID, language tag,
Document hash, authoring metadata, and creation time.
* * *
# Important Principle
Revisions MUST reference:
```text
immutable object references only
```
* * *
# Forbidden
```text
revision -> mutable asset HEAD
```
* * *
# Allowed
```text
revision -> sha256 immutable snapshot
```
* * *
# 4. sha256:
## Purpose
Immutable content-addressed object identity.
* * *
# Example
```text
sha256:deadbeef...
```
* * *
# Properties
Property Value immutable yes content-addressed yes deduplicatable yes cacheable yes
* * *
# Typical Targets
- DrawIO payload
- Excalidraw payload
- PDF binary
- Image
- CSS snapshot
- JS snapshot
- PPTX binary
- XLSX binary
* * *
# Important Principle
sha256 objects are:
```text
historical truth
```
* * *
# 5. asset:
The normative lifecycle, freezing, authorization, and retention rules are in
[`asset-model.md`](asset-model.md).
## Purpose
Mutable editable workspace object.
* * *
# Example
```text
asset:drawio:network-core
asset:xlsx:q1-budget
asset:slide:roadmap
```
* * *
# Properties
Property Value mutable yes editable yes workspace-oriented yes
* * *
# Important Principle
Assets represent:
```text
current editable HEAD
```
* * *
# Save Flow
```text
asset mutable HEAD
↓
save
↓
snapshot
↓
sha256 immutable object
```
For HTML Revisions, supported embedding attributes containing an `asset:`
address are resolved at save time. Unresolved Asset HEADs reject the save.
* * *
# Important Principle
Asset identity represents:
```text
semantic continuity of editing
```
NOT immutable historical truth.
* * *
# 6. alias:
## Purpose
Semantic indirection pointer.
* * *
# Example
```text
alias:latest-network-design
```
* * *
# Properties
Property Value mutable yes semantic yes canonical no
* * *
# Typical Uses
- latest stable design
- current handbook
- canonical public URL
- migration pointer
* * *
# 7. share:
## Purpose
Delegated capability projection.
* * *
# Example
```text
share:abcdef
```
* * *
# Typical Projection
```text
/s/abcdef
```
* * *
# Properties
Property Value temporary usually delegated yes capability-bound yes
* * *
# Internal Model
Share addresses usually resolve to:
```text
macaroon delegated capability
```
* * *
# 8. derived:
## Purpose
Generated/transformed object identity.
* * *
# Example
```text
derived:thumbnail:sha256:abcd
derived:ocr:sha256:abcd
derived:preview-svg:sha256:abcd
```
* * *
# Properties
Property Value generated yes reproducible usually immutable preferred
* * *
# Typical Derived Objects
- thumbnails
- OCR text
- SVG previews
- rendered PDF pages
- AI summaries
- embeddings
* * *
# 9. external:
## Purpose
Mounted foreign object reference.
* * *
# Example
```text
external:gdrive:file123
external:figma:abcd
external:slack:thread456
```
* * *
# Properties
Property Value foreign ownership yes mutability external-defined projection-capable yes
* * *
# Runtime Resolution Pipeline
```text
path
↓
uuid
↓
revision
↓
projection
↓
embedded object resolution
↓
sha256 / asset / external
↓
renderer
```
* * *
# Projection Principle
## Address != Rendering
Rendering is determined by:
- mime type
- object class
- projection adapter
- user context
- runtime capability
* * *
# Example
```text
uuid:abcd
```
may render as:
- HTML article
- PDF viewer
- slide deck
- spreadsheet runtime
- whiteboard canvas
depending on projection adapter.
The adapter contract, bounded-delivery rules, and structured-format roadmap
are defined in [projection-adapters.md](projection-adapters.md).
* * *
## Raw Document Projection
Raw payload delivery is a projection, not another identity namespace. The
HTTP form therefore carries an explicit internal address:
```text
/v/raw/path:/manual/report
/v/raw/uuid:550e8400-e29b-41d4-a716-446655440000
/v/raw/rev:018f6b5d...
```
Viewer embeds `path:` when displaying the current semantic projection.
Immutable Revision Viewer embeds `rev:`. A bare `/raw/<semantic-path>` is
forbidden because it conflates projection, reachability, and identity.
## Path Rename
Rename changes reachability, not Page identity. It is committed atomically as:
```text
link(new-path, existing-page-uuid)
unlink(old-path, existing-page-uuid)
```
Recursive rename applies the same mapping to every descendant in one database
transaction. Destination collisions abort the entire operation. When the
basename of an extension-bearing file changes, the latest language projections
receive a new Revision carrying the new `filename`; older Revisions remain
immutable.
* * *
# Mutability Model
| Layer | Mutable |
| --- | --- |
| `path:` | yes |
| `alias:` | yes |
| `asset:` | yes |
| `uuid:` | no |
| `rev:` | no |
| `sha256:` | no |
| `derived:` | preferably no |
* * *
# Important Separation
## Workspace Plane
Mutable editing world.
Contains:
- asset:
- path:
- alias:
* * *
# Revision Plane
Immutable historical world.
Contains:
- rev:
- sha256:
- derived:
* * *
# Core Architectural Principle
Pages Wiki separates:
```text
semantic navigation
identity
content storage
projection
editing
history
```
into independent planes.
* * *
# Conceptual Summary
| Layer | Responsibility |
| --- | --- |
| `path:` | Semantic routing |
| `uuid:` | Stable Page/Object identity |
| `rev:` | Historical snapshot identity |
| `sha256:` | Immutable content reality |
| `asset:` | Mutable editing continuity |
| Projection | Runtime interpretation |
| Capability | Authorized reachability |
* * *
# Final Conceptual Direction
Pages Wiki evolves toward:
```text
semantic knowledge routing
+
immutable object graph
+
projection-oriented rendering
+
capability-based reachability
```
rather than:
```text
filesystem-oriented page hierarchy
```
+438
View File
@@ -0,0 +1,438 @@
# Overview
## Concept
Pages Wiki is designed as **semantic locality driven knowledge system** rather than a traditional filesystem wiki.
### Key properties
- Hierarchy-oriented UI
- Graph-capable Internal model
- Language-neutral Semantic paths
- Capability-centric authorization
- Delegated access via macaroons xxx
## Knowledge City Model
Pages Wiki don’t only comprises Machine friendly but also Human-Facing friendly with Knowledge City Model.
Knowledge City Model constitute five administrative division unit called ‘domain’, ‘quartier’, ‘street’, ‘spot’, ‘page’.
- ‘page’ is minimal knowledge unit.
- ‘spot’ constitute multiple pages. Namely, spot is minimal knowledge group.
- An overgrown knowledge spot can’t be upgraded to a street.
- ‘zone’ is managed unit in data structure.
- ‘street’ is group of spot. ‘street’ used minimal knowledge city block.
- If existed mixed spot and various page, it is unconsolidated street.
- ‘quartier’ can be called if it consists of an aggregation of streets delineated through urban planning.
- An overgrown knowledge street can be upgraded to a quartier.
- ‘Domain’ is really site group. For example, ’Domain’ may indicate division and department group, project, and team. ‘Domain’ used as subdomain space in URI.
- ‘Domain’ managed by one ‘Campus’.
```mermaid
graph TD
Cm[Campus]
DmA[Domain: Sales Unit]
DmB[Domain: Technical Unit]
DmC[Domain: Management Unit]
%% Campus から Domain への接続
Cm-..->DmA
Cm-..->DmB
Cm-..->DmC
%% Zone定義(Quartier と Street を内包し、縦に並ぶよう調整)
subgraph Zone ["Zone"]
direction TB
%% Quartier レ法
QtA[Quartier: Network]
QtB[Quartier: Server]
QtC[Quartier: Application]
%% Street レ法
StA[Street: DNS]
StB[Street: Web]
StC[Street: Mail]
%% Zone内での上下関係を固定するための接続
QtB-->StA
QtB-->StB
StB-.if it is overgrown, upgrade to 'quartier'.->QtB
QtB-->StC
end
%% Domain から Zone(Quartier) への接続
DmB-->QtA
DmB-->QtB
DmB-->QtC
%% Zone(Street) から下位レイヤーへの接続
SpA[Spot: Web Infrastructure]
SpB[Spot: Wiki Application]
SpC[Spot: Search Engine]
StB-->SpA
StB-->SpB
StB-->SpC
%% Spot から Page への接続
PgA[Page: Access Control Model]
PgB[Page: Addressing Model]
PgC[Page: Authenticating Model]
SpB-->PgA
SpB-->PgB
SpB-->PgC
```
## Internal Semantic Structure
Pages Wiki is arranged by machine-friendly semantic structure.
The detailed responsibilities, invariants, schema, projections, API surface,
and implementation order for Quartier, Street, Spot, and MagicPage are defined
in [Knowledge City Model Detailed Design](knowledge-city-model.md).
Collaboration, notification, delegated sharing, extension providers, external
storage, malware inspection, controller DR, and multi-node HA must preserve
these identities through the contracts in
[Platform Extension Architecture](platform-extension-architecture.md). These
features extend Page/Revision/City projections; they do not introduce alternate
Page identity, mutable Revision payloads, or filesystem-style ownership.
- ‘ZoneTree’ is arranged tree-structured model for control ‘quartier’ and ‘street’, and so ‘spot’ as external pointer. ZoneTree referenced from domain.
- ‘SpotGraph’ is page pointer graph from spot.
- SpotGraph point page ID. Multiple spot can any page with page ID(called ‘MagicPage’).
- Revision
- A Page UUID owns an ordered Revision history.
- Each immutable Revision has a Revision UUID and references an immutable
Document by SHA-256.
- Revision identity and Document content identity are distinct.
- Revisions carry a BCP 47 language tag; `und` represents legacy or
language-unspecified content.
```mermaid
graph LR
Dm[Domain]
ZT[Zone Tree]
SG[Spot Graph]
PG[Pages]
RV[Revisions]
Dm--Domain refer to ZoneTree-->ZT
ZT--ZoneTree refer to spot with SpotGraph-->SG
SG--SpotGraph refer to page-->PG
PG--page refer to revisions-->RV
```
### MagicPage
The MagicPage can reach from multiple spot without depending quartier and street. So, A single Page may appear in multiple Spots.
This creates: rooted multitree
instead of strict filesystem hierarchy.
```mermaid
graph LR
SPA[Spot A]
SPB[Spot B]
SPC[Spot C]
P1[Page UUID=P1]
P2[Page UUID=P2]
SPA --> P1
SPB --> P1
SPC --> P2
```
## Language Projection Model
```mermaid
graph LR
REQ[Request]
AL[Accept-Language]
P[Page UUID]
JAJP[Revision ja-JP]
JA[Revision ja]
EN[Revision en]
REQ --> AL
AL --> P
P --> JAJP
JAJP -->|not found| JA
JA -->|not found| EN
```
### Example
```http
GET /dev/api/auth
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
```
# Canonical Identity Model
```mermaid
graph TD
DOMAIN[Domain UUID]
PATH[Semantic Path]
UUID[Page UUID]
REV[Revision]
DOMAIN --> PATH
PATH --> UUID
UUID --> REV
```
### Important Principle
```text
path != object
representation != object
(domain_uuid, path) = semantic address
object UUID = instance-global identity
```
A Domain owns a semantic path namespace, not the Page Object itself. The same
normalized path may exist in multiple Domains without conflict, and multiple
Domains may bind different paths to the same Page UUID. Cross-Domain links use
an absolute URL containing the destination FQDN. See
`domain-namespace-federation.md` for local/remote placement and Campus
authority modes.
## Authentication / Authorization Flow
```mermaid
graph TD
OIDC[OIDC Provider]
PR[Principal]
MB[Membership]
RL[Role]
CAP[Capability Graph]
OIDC --> PR
PR --> MB
MB --> RL
RL --> CAP
```
### Important Separation
| Layer | Responsibility |
| --- | --- |
| OIDC | Identity proof |
| Principal | Canonical internal identity |
| Membership | Organizational mapping |
| Role | Semantic grouping |
| Capability | Actual authority |
## Capability Model
```mermaid
graph TD
PR[Principal]
CAP[Capabilities]
SP[Spot]
PAGE[Page]
PR --> CAP
CAP --> SP
SP --> PAGE
```
## Example
```text
Alice
└─ auth-api:read
```
Spot:
```text
Auth API
└─ requires auth-api:read
```
## Capability Evaluation
```mermaid
graph TD
REQ[Read Request]
PR[Principal]
SP[Spot]
CAP[Capability Check]
ALLOW[Allow]
DENY[Implicit Deny]
REQ --> PR
REQ --> SP
PR --> CAP
SP --> CAP
CAP -->|has capability| ALLOW
CAP -->|missing capability| DENY
```
### Important Principle
```text
default deny
positive grants only
```
## Macaroon Delegation
```mermaid
graph TD
PR[Principal]
CAP[Capability]
MAC[Macaroon]
CAV[Caveats]
USR[Temporary User]
PR --> CAP
CAP --> MAC
MAC --> CAV
MAC --> USR
```
### Caveat Examples
- expires
- readonly
- network restriction
- lang restriction
- path restriction
## Share Link Model
```mermaid
graph TD
SHARE["/s/abcdef"]
MAC[Anonymous Macaroon]
SP[Spot]
VIEW[Read-only Projection]
SHARE --> MAC
MAC --> SP
SP --> VIEW
```
## Storage Model
```mermaid
graph TD
PAGE[Page UUID]
REV1[Revision 1]
REV2[Revision 2]
REV3[Revision 3]
PAGE --> REV1
PAGE --> REV2
PAGE --> REV3
```
Metadata is stored in the database. Immutable Document payloads use a global
content-addressed filesystem:
```text
documents/
└─ sha256/
└─ ab/
└─ abcdef...
```
The payload extension is not used as identity. MIME type and canonical format
are metadata. A Revision row references the hash and never references a
mutable asset HEAD.
## Runtime Rendering Pipeline
```mermaid
graph TD
REQ[HTTP Request]
PATH[Semantic Path]
UUID[Page UUID]
LANG[Language Resolution]
REV[Revision]
AUTH[Capability Evaluation]
RENDER[Render]
REQ --> PATH
PATH --> UUID
UUID --> LANG
LANG --> REV
REV --> AUTH
AUTH --> RENDER
```
## Overall Architectural Direction
```mermaid
graph TD
UI[Hierarchy UI]
TREE[Rooted Tree]
GRAPH[Semantic Graph]
UUID[UUID Identity]
LANG[Language Projection]
CAP[Capability Access]
MAC[Macaroon Delegation]
UI --> TREE
TREE --> GRAPH
GRAPH --> UUID
UUID --> LANG
LANG --> CAP
CAP --> MAC
```
## Final Summary
### Pages Wiki is:
- hierarchy-oriented for humans
- graph-capable internally
- semantic-locality-driven
- UUID identity based
- language-neutral
- capability-centric
- projection-oriented
### NOT:
- filesystem ACL centric
- path identity centric
- language hierarchy centric
+34
View File
@@ -0,0 +1,34 @@
# Archive Import and Knowledge City Planning
Archive import is a staged, auditable operation. Uploading an archive never
writes Pages directly.
## Pipeline
1. Store the uploaded ZIP or tar-family archive in private import storage.
2. Queue `import.analyze`; foreground requests always take scheduler priority.
3. Validate entry names, link types, file count and expanded byte limits.
4. Produce an immutable dry-run manifest containing source path, destination
Path, detected content type and initial Quartier/Street/Spot suggestions.
5. Allow a curator to edit, merge, exclude and approve suggestions.
6. Queue import execution in bounded batches. Markdown is transpiled to the
canonical HTML Document while its source representation remains available.
7. Record created UUIDs and topology operations in an import journal so a
session can be reviewed, retried or rolled back.
## Safety limits
- archive upload: 512 MiB;
- expanded content: 2 GiB;
- entries: 10,000;
- absolute paths, `..`, NUL, hard links and symbolic links are rejected;
- supported staging formats: ZIP, tar, tar.gz/tgz and tar.xz/txz.
## Initial suggestion rules
The first directory component proposes a Quartier, the second proposes a
Street, and the nearest containing directory proposes a Spot. Markdown receives
higher initial confidence than opaque assets. Later scoring incorporates
front matter, headings, README/index portals, internal links, vocabulary and
existing City boundaries. Suggestions never mutate City topology until a
curator confirms the plan.
+247
View File
@@ -0,0 +1,247 @@
# Asset Model
## 1. Purpose
An Asset is a mutable authoring identity whose HEAD points to one immutable
Document. It represents continuity of editing for binary or application-native
material such as an image, DrawIO scene, Excalidraw scene, spreadsheet, slide
deck, audio file, or video file.
An Asset is not:
- a Semantic Path or a Viewer URL;
- a Page Revision;
- immutable historical truth;
- an authorization capability;
- a remote-instance address.
The identity layers remain distinct:
| Identity | Meaning | Mutable |
| --- | --- | --- |
| `asset:<type>:<name>` | Editable Asset identity and current HEAD | yes |
| `sha256:<hash>` | Exact immutable Document bytes | no |
| `rev:<uuid>` | Immutable Page Revision that may refer to Documents | no |
| `path:/...` | Domain-scoped semantic reachability | yes |
## 2. Address and scope
The canonical local address is:
```text
asset:<type>:<name>
```
Examples:
```text
asset:image:knowledge-city-logo
asset:drawio:network-core
asset:xlsx:q1-budget
```
`type` is a projection/editor hint, not trusted MIME metadata. `name` is the
stable authoring name. The complete address is Domain-local, case-sensitive,
and unique by `(domain_uuid, address)` in the `assets` table.
Asset authoring identity is Domain-scoped so separate Domains may independently
own `asset:image:logo`. Immutable Documents remain content-addressed and may be
deduplicated across Domains. A local `asset:` address must never be resolved on
another instance. A remote resource requires an absolute HTTPS URL and an
explicit federation or external-object contract.
## 3. Stored state
The current additive schema is:
| Column | Meaning |
| --- | --- |
| `domain_uuid` | Owning Domain; part of the composite primary key |
| `address` | Canonical `asset:` identity; part of the composite primary key |
| `object_uuid` | Stable Object UUID with kind `asset` |
| `head_document_hash` | Current immutable Document SHA-256; empty means no HEAD |
| `created_at_ms` | Asset creation time |
| `content_type` | Mutable MIME metadata for the current HEAD |
| `filename` | Mutable filename metadata for the current HEAD |
| `size_bytes` | Current HEAD byte length |
| `updated_at_ms` | Last HEAD update time |
The bytes are stored in the Document Store under their SHA-256. The Asset row
contains no duplicate body. Filename, MIME type, and size describe the mutable
HEAD but do not participate in Document identity. Immutable delivery uses
bounded content detection when historical metadata is unavailable.
## 4. State transitions
### Create or update HEAD
```text
input bytes
-> calculate SHA-256
-> atomically persist immutable Document
-> compare with Asset HEAD
-> create Asset or move HEAD
```
Writing identical bytes with unchanged MIME and filename is a no-op. Correcting
MIME or filename records a metadata/history update without changing the hash.
Moving HEAD never mutates or overwrites the
old Document. The local CLI currently implements this operation through
`put LOCAL asset:<type>:<name>` and `edit asset:<type>:<name>`.
Asset HEAD updates do not create Page Revisions. An old Document remains live
when a Page Revision has frozen a reference to it; otherwise it may become
garbage after it is no longer an Asset HEAD. Garbage collection must treat
current Asset HEADs and `revision_document_refs` as roots.
### Read
`view`, `cat`, and `get` resolve the Asset HEAD at operation time. These are
mutable reads and must not be used for reproducible rendering or historical
export. Reproducible consumers use the resolved `sha256:` identity.
### Delete
Administrator HTTP deletion removes the mutable Asset identity only; it does
not delete a Document still
referenced by a Revision, another Asset HEAD, export, or retention root.
Automatic retention and physical Document collection policy remain pending.
## 5. Revision save and freezing
A saved Page Revision must never use a live `asset:` dependency as its rendered
payload. It does retain the authoring address as provenance so a later edit can
resolve the then-current HEAD. For HTML payloads, the server resolves `asset:`
values at save time:
| Authoring input | Stored Revision |
| --- | --- |
| `asset-ref="asset:…"` | Retain `asset-ref`; add/update `immutable-ref="sha256:<hash>"` |
| `immutable-ref="asset:…"` | Normalize to retained `asset-ref` plus fixed `immutable-ref` |
| `src="asset:…"` | Fixed `src="/_/obj/sha256:<hash>"` plus `data-pageswiki-asset-src="asset:…"` |
| `href="asset:…"` | Fixed `href` plus `data-pageswiki-asset-href` provenance |
| `poster="asset:…"` | Fixed `poster` plus `data-pageswiki-asset-poster` provenance |
| `data="asset:…"` | Fixed `data` plus `data-pageswiki-asset-data` provenance |
Only HTML attribute values are transformed. Explanatory prose, code blocks,
and non-HTML payloads are not rewritten. A missing Asset or an Asset without a
valid HEAD rejects the save with `ErrEmbeddedAssetUnavailable`; silently
leaving a mutable dependency is forbidden.
On a later save, the provenance address is resolved again and the fixed hash is
updated to the current Asset HEAD. Merely viewing an old Revision never resolves
the mutable address and therefore remains reproducible.
### Authoring forms
Markdown may use ordinary resource and link syntax because compilation produces
the supported HTML attributes:
```markdown
![Knowledge City logo](asset:image:knowledge-city-logo)
[Download the workbook](asset:xlsx:q1-budget)
```
Equivalent HTML examples are:
```html
<img src="asset:image:knowledge-city-logo" alt="Knowledge City logo">
<a href="asset:xlsx:q1-budget">Download the workbook</a>
<video poster="asset:image:intro-poster">
<source src="asset:video:intro">
</video>
<embedded-object
kind="drawio"
asset-ref="asset:drawio:network-core">
</embedded-object>
```
`asset:` is accepted only in `asset-ref`, legacy `immutable-ref`, `src`, `href`,
`poster`, and `data`. CSS `url()`, `srcset`, inline scripts, arbitrary
`data-*` attributes, and plain text are not resolvers. They require a future
typed parser rather than unsafe textual replacement.
### Access surfaces
| Surface | Address | Semantics |
| --- | --- | --- |
| CLI authoring | `asset:<type>:<name>` | Mutable HEAD read/write in selected Domain |
| Administrator HEAD URL | `/v/raw/asset:<type>:<name>` | Resolves current HEAD on every request; private and non-canonical |
| HTML/Markdown authoring | `asset:<type>:<name>` | Resolved only while saving a Revision |
| Stored semantic reference | `asset-ref="asset:…"` | Provenance for later editing; never rendered directly |
| Stored immutable reference | `sha256:<hash>` | Exact dependency identity |
| Browser delivery | `/_/obj/sha256:<hash>` | Authorized immutable GET/HEAD/Range |
| Management API | `/_/api/v1/assets?address=asset:…` | Domain-admin metadata and mutation surface |
The mutable Asset URL is an authenticated administrator authoring projection;
it is never emitted into published Pages or historical Revisions. It uses a
private revalidation cache policy and reports both the Asset address and
resolved HEAD hash in response headers. Published Pages always load the frozen
Document URL.
Every frozen dependency is recorded as:
```text
revision_document_refs(revision_uuid, document_hash)
```
This relation is part of Revision truth. It enables dependency inspection,
authorization, export, and garbage-collection reachability without reparsing
historical HTML.
## 6. Delivery and authorization
Immutable bytes are delivered through:
```text
/_/obj/sha256:<hash>
```
Knowing a hash is not authorization. Delivery succeeds only when the Document
is either the body of, or a frozen dependency of, a Revision whose Object has a
readable Path in the current Domain. The response exposes Object, Revision, and
Document identities in the PagesWiki metadata headers and supports ETag, HEAD,
and byte ranges.
The current HEAD of a Domain Asset may also be inspected through the same
immutable URL by a Domain or Campus administrator, even before any Revision has
frozen it. This administrative exception is for Asset management and does not
make the mutable HEAD anonymously readable. Once frozen into a Page Revision,
ordinary access follows that Page's read authorization.
The trusted local CLI bypasses HTTP Capability evaluation and is controlled by
database and filesystem permissions. The administrator HTTP API is restricted
to Domain or Campus administrators and requires an Asset HEAD ETag for updates
and deletion, or `If-None-Match: *` for creation. It records immutable HEAD
history with actor identity. Moving this endpoint into the typed policy matrix
and general audit outbox remains pending. Last-writer-wins HTTP updates are not
accepted.
## 7. Consistency rules
1. `head_document_hash` and every frozen dependency must be a lowercase,
64-character SHA-256.
2. Asset HEAD movement never changes existing Documents or Revisions.
3. Revision save resolves all supported embedded Asset references or fails.
4. `asset:` is authoring identity; `sha256:` is delivery/storage identity.
5. A hash, Asset address, or Object UUID never grants access by itself.
6. Cross-instance Asset resolution is forbidden without an explicit origin.
7. GC must preserve Documents reachable from Revisions, frozen references,
current Asset HEADs, and configured retention roots.
## 8. Implementation status
| Capability | Status |
| --- | --- |
| Local CLI create/update/read/edit | active |
| Content-addressed Document persistence | active |
| HTML save-time freezing | active |
| Revision-to-Document dependency records | active |
| Authorized immutable HTTP delivery | active |
| Asset owner excluded from Zombie Object GC | active |
| Asset MIME/filename/size metadata | active |
| Administrator HTTP CRUD and ETag/CAS updates | active |
| Initial Domain Asset management UI | active |
| History/restore and dependency detail UI | active |
| Delete/retention UI and audit trail | designed, not implemented |
| Remote/federated Asset synchronization | not designed as implicit lookup |
+152
View File
@@ -0,0 +1,152 @@
# Authentication and Authorization Backend
## Boundary
Authentication proves an identity. Every authenticator produces the same
internal `principal_uuid`; authenticators never grant document access directly.
Authorization is Domain-scoped and evaluates positive grants only:
```text
request -> session -> principal -> Domain membership -> role -> capability
```
Campus owns trusted identity-provider configuration. A Domain owns membership,
roles, grants, session policy, and the default authorization mode. Managed
Campus provider metadata is inherited from its controller; secrets remain on
the instance that performs authentication and are never federated.
## Authentication methods
| Method | Stable external key | Secret location |
| --- | --- | --- |
| password | normalized username | Argon2id verifier in credential table |
| OIDC | exact `(issuer, subject)` | encrypted client secret/config |
| LDAP | `(provider UUID, immutable directory attribute)` | encrypted bind secret |
| TOTP | principal + factor UUID | encrypted seed; recovery codes hashed |
| magic link | normalized verified email | one-use hashed challenge |
| device approval | requesting-device challenge UUID | one-use hashed challenge |
OIDC groups and LDAP groups are attributes. Explicit mapping rules may create
or remove Membership/Role bindings, but group names are not capabilities.
The route policy, internal group schema, `/g/` namespace, and endpoint matrix
are specified in [Endpoint Authorization and Groups](authorization-groups.md).
## Core records
- `principals`: canonical person/service identity and lifecycle state.
- `principal_identities`: unique provider subjects attached to a Principal.
- `auth_credentials`: password/TOTP/recovery material and version metadata.
- `domain_memberships`: Principal membership in one Domain.
- `auth_roles`, `auth_role_bindings`: Domain roles and membership assignment.
- `groups`, `group_members`, `auth_group_role_bindings`: Domain-scoped
Principal collections and their Role assignment.
- `auth_capability_grants`: positive operation grants with typed targets.
- `auth_sessions`: opaque, hashed, rotating browser sessions.
- `auth_challenges`: short-lived one-use login/MFA/device challenges.
- `auth_audit_log`: append-only authentication and policy decisions.
Capabilities use verbs `read`, `create`, `upload`, `write`, `rename`, `delete`,
`link`, `manage`, and `delegate`. Targets are `domain`, `quartier`, `street`, `spot`, `path`, or
`object`. Locality inheritance is resolved by the address model; an exceptional
Page/Object grant does not rewrite the path hierarchy.
## Evaluation
1. Resolve Domain before reading the session.
2. Hash the opaque cookie and load an unexpired, unrevoked session for that
Domain. Reject suspended/quarantined Principals.
3. Resolve Membership and its Role bindings.
4. Match the requested verb and target against positive grants. `manage`
includes administrative operations but does not imply `delegate`.
5. Record denied sensitive operations and every policy/configuration mutation.
No matching grant means deny. During migration, `authorization_mode=legacy`
leaves existing anonymous behavior intact. Administrators bootstrap an owner,
verify access, then switch a Domain to `enforcing`. New Domains should default
to `enforcing` once the bootstrap flow is complete.
## HTTP flows
- `/_/auth/login`, `/_/auth/logout`, `/_/auth/callback/oidc/{provider}`
- `/u/{username}` is the Domain-scoped profile and user-Wiki root.
`/u/{username}/_/edit` is its owner-only profile editor and
`/_/auth/profile` redirects there. Other descendants are ordinary semantic
Wiki paths. Usernames exclude dots so the public handle can be derived as
`{username}.{domain FQDN}` without ambiguity.
- `/_/auth/challenge/password`, `/totp`, `/magic-link`, `/device`
- `/_/api/v1/auth/session`, `/principals`, `/roles`, `/grants`, `/audit`
Cookies are `Secure`, `HttpOnly`, `SameSite=Lax`, host-only, and contain only a
random secret whose SHA-256 hash is stored. Login rotates the session; password
or factor changes revoke all Principal sessions. State/nonce/PKCE are mandatory
for OIDC. Magic links and device approvals store only a token hash, are
single-use, expire quickly, and are bound to Domain and intended action.
TOTP seeds are encrypted with AES-GCM using a 256-bit instance key stored as
`auth.key` beside the Document Store (`0600`), or derived from
`PAGESWIKI_AUTH_KEY`. Enrollment remains disabled until a valid six-digit code
is confirmed. Login challenges expire after five minutes, allow five attempts,
and reject reuse of an accepted 30-second counter.
OIDC providers are configured per Domain from the authentication panel. The
flow uses discovery, Authorization Code, PKCE S256, state, and nonce, then
resolves the subject through UserInfo. A first login may bind `(issuer, sub)`
only to an existing Principal with the same verified email; it never creates a
role or capability from provider claims. Client secrets are encrypted with the
instance authentication key.
LDAP providers are also Domain-scoped. The implemented login sequence follows
the same separation used by Wiki.js' LDAP authenticator:
1. connect to an `ldap://` or `ldaps://` endpoint with an 8-second socket
deadline; optionally upgrade an `ldap://` connection with StartTLS;
2. bind the configured search service account, or use an anonymous search when
both bind fields are empty;
3. insert the RFC 4515-escaped login into a configured filter containing
`{{username}}`, search below the configured Base DN, and require exactly one
result (server size limit 2, time limit 6 seconds);
4. read an explicitly configured immutable ID, local username, email, and
display-name attribute;
5. bind as the returned user DN with the submitted password. A search result by
itself is never accepted as proof of authentication;
6. resolve the first login by an exact unique local username or email, then
persist `(provider UUID, immutable ID)`. Following logins use only that
immutable binding. Optional automatic provisioning creates an ordinary
`member` with no local password credential.
The immutable attribute should be `entryUUID` for common LDAP servers or the
binary `objectGUID` for Active Directory. DN, email, display name, and account
name are mutable attributes and therefore are not stable subjects. Bind
passwords use the instance authentication-key encryption; leaving the password
blank in the settings form preserves the existing encrypted value. TLS
certificate validation is on by default, a private CA can be appended as PEM,
and disabling validation is an explicit per-Domain administrator action.
The settings panel exposes a saved-configuration login test. User passwords are
used only for the user-DN bind and are neither persisted nor logged. Connection
admission is bounded to four process-wide LDAP operations. The browser receives
the same generic invalid-credentials response for lookup and password failures;
the server log retains the provider-side error without the submitted username
or password.
SMTP magic links target existing active/read-only Principals by normalized
email. The public request response never reveals whether an address exists.
Links contain a random token whose hash alone is stored, expire after fifteen
minutes, and are consumed atomically once. SMTP credentials use the same
encrypted provider-secret storage. Delivery is admitted through a bounded
background slot so an SMTP server cannot hold the login request open.
LDAP and SMTP run through bounded worker queues with timeouts; request handlers
do not wait indefinitely on an external directory or mail server. A durable
authentication-attempt quota keyed by Domain, normalized account identifier,
source prefix, and challenge kind remains required before an Internet-facing
multi-tenant deployment; bounded provider admission is not a rate limiter.
## Delivery order
1. Common schema, Principal normalization, sessions, RBAC evaluation, audit.
2. Bootstrap owner plus password/Argon2id and optional TOTP.
3. OIDC Authorization Code + PKCE.
4. SMTP magic link and device approval challenges.
5. LDAP bind/search with immutable identity mapping.
6. Delegated macaroon capabilities after canonical RBAC is enforced.
+642
View File
@@ -0,0 +1,642 @@
# Pages Wiki vNext Authentication / Authorization Draft
## Goal
Separate:
```text
Authentication
Identity
Capability
Delegation
Projection
```
into independent layers.
Avoid tightly coupling:
```text
OIDC groups
filesystem ACLs
path hierarchy
```
to the knowledge topology.
* * *
# Core Philosophy
## Authentication != Authorization
Authentication answers:
```text
Who are you?
```
Authorization answers:
```text
What may you do?
```
These are intentionally separated.
* * *
# High-Level Architecture
```text
OIDC
↓
Principal
↓
Membership / Roles
↓
Capability Graph
↓
Macaroon Delegation
↓
Runtime Policy Evaluation
```
* * *
# Layer 1: Authentication
## Responsibility
Identity proof only.
* * *
# Recommended Mechanism
OIDC / OpenID Connect.
Examples:
- Keycloak
- Authentik
- Azure AD
- Google Workspace
- GitHub OIDC
* * *
# OIDC Output
Example claims:
```json
{
"iss": "...",
"sub": "...",
"email": "...",
"groups": [...]
}
```
* * *
# Important Principle
OIDC groups are NOT canonical authorization objects.
They are only:
```text
external identity attributes
```
* * *
# Layer 2: Principal
## Responsibility
Canonical internal identity normalization.
* * *
# Principal Model
```text
principal_id
issuer
subject
display_name
email
```
* * *
# Important Principle
The canonical identity inside Pages is:
```text
principal_id
```
NOT:
```text
OIDC group
email address
username
```
* * *
# Layer 3: Capability Model
## Responsibility
Represent authority within the knowledge topology.
* * *
# Capability Philosophy
Capabilities are attached primarily to:
```text
Zone
Spot
```
rather than individual Pages.
* * *
# Why
Knowledge naturally clusters around semantic localities.
ACLs scale better when attached to locality.
* * *
# Example
```text
Spot(Auth API)
allow:
engineering-reader
api-editor
```
Pages inherit effective visibility from their locality.
* * *
# Capability Model
```text
principal
↓
membership
↓
role
↓
capability
```
* * *
# Example
```text
engineering-team
↓
api-editor
↓
write Spot(Auth API)
```
* * *
# Important Principle
Roles are internal semantic policy objects.
They are NOT identical to OIDC groups.
* * *
# OIDC Mapping
```text
OIDC group
↓
Pages membership
↓
Pages role
↓
Capability
```
* * *
# Capability Target Types
Capabilities may target:
| Object Type | Meaning |
| --- | --- |
| Zone | Containment locality |
| Spot | Semantic locality |
| Page | Exceptional override only |
| Binding | Projection-level visibility |
* * *
# Default Authorization Strategy
## Default Deny
No capability means:
```text
access denied
```
* * *
# Positive Grant Only
Avoid large explicit deny graphs.
Prefer:
```text
grant omission
```
instead of:
```text
explicit deny
```
* * *
# Why
Explicit deny causes:
- precedence complexity
- inheritance conflicts
- ACL explosion
- runtime ambiguity
* * *
# Recommended Model
```text
allow-only locality policies
```
plus:
```text
principal-side overlays
```
for exceptional cases.
* * *
# Exceptional Restriction Handling
Instead of:
```text
deny alice
```
prefer:
```text
alice.status = suspended
```
or:
```text
alice lacks capability
```
* * *
# Principal States
Examples:
```text
active
readonly
suspended
quarantined
audit-only
```
* * *
# Layer 4: Macaroon
## Responsibility
Portable delegated constrained capability.
* * *
# Important Principle
Macaroon is NOT the canonical ACL database.
Macaroon is:
```text
authority artifact
delegated capability token
portable constrained access proof
```
* * *
# Macaroon Role
Macaroons transport delegated authority.
* * *
# Example
Canonical server-side capability:
```text
Alice
└─ read Spot(Auth API)
```
Delegated macaroon:
```text
read-only
spot=auth-api
expires<2026-02-01
office-network-only
```
* * *
# Caveats
Macaroon caveats attenuate authority.
Examples:
Caveat Meaning expires time restriction network source network restriction readonly capability narrowing path locality restriction lang projection restriction method operation restriction
* * *
# Important Property
Macaroons can only:
```text
reduce authority
```
never expand it.
* * *
# Runtime Validation
```text
1. Verify macaroon signature
2. Verify caveats
3. Verify delegated capability validity
4. Apply runtime policy
```
* * *
# Share Links
Example:
```text
/s/abcdef
```
may internally represent:
```text
anonymous delegated macaroon capability
```
* * *
# Important Property
Share links may work without OIDC login.
This enables:
```text
identity-less delegated access
```
* * *
# Capability vs ACL
## Traditional ACL
```text
Object
└─ Subjects
```
* * *
# Capability-Oriented Model
```text
Principal
└─ Possessed Authorities
```
* * *
# Real-World Analogy
Pages authorization behaves more like:
```text
building access control
```
than filesystem ACLs.
* * *
# Example
```text
Zone = building
Spot = room
Capability = key
Macaroon = temporary visitor pass
```
* * *
# Locality Unlock Model
## Spot
```text
requires capability:
auth-api:read
```
* * *
# Principal
```text
possesses:
auth-api:read
```
* * *
# Runtime
```text
Does principal possess required capability?
```
* * *
# Capability Delegation
Example:
```text
Alice delegates:
read-only access
to Spot(Auth API)
valid for 24 hours
```
This maps naturally to:
```text
temporary visitor badge
```
* * *
# Runtime Authorization Evaluation
## Without Macaroon
```text
principal session
↓
effective capability lookup
```
* * *
# With Macaroon
```text
verify macaroon
↓
apply caveats
↓
treat as delegated capability
```
* * *
# Runtime Evaluation Components
| Component | Responsibility |
| --- | --- |
| Principal | Identity |
| Capability Graph | Canonical authority |
| Macaroon | Delegated authority |
| Runtime Policy | Dynamic constraints |
| Effective Cache | Acceleration |
* * *
# Runtime Constraints
Examples:
```text
time
network
risk
device
lang
projection
```
* * *
# Effective Capability Cache
Recommended for scalability.
Example:
```text
principal_effective_capabilities
```
* * *
# Important Principle
The source of truth is:
```text
server-side capability graph
```
NOT macaroon tokens.
* * *
# Architectural Direction
Layer Model Authentication OIDC Identity Principal Authorization Capability graph Delegation Macaroon Constraints Caveats Runtime Effective policy evaluation
* * *
# Conceptual Summary
Pages Wiki authorization is evolving toward:
```text
semantic locality capability system
```
rather than:
```text
filesystem ACL system
```
+410
View File
@@ -0,0 +1,410 @@
# Endpoint Authorization and Groups
## Scope
2026-09-14 extension: [locality access and publication](locality-access-publication.md)
adds restrictive named user/group layers over existing grants and a separate
explicitly approved anonymous semantic/raw path. For Objects, all local
restrictive alias caps apply before the original positive-grant/any-readable-
alias rule below. Existing group profiles and administrative roles are unchanged.
This document completes the backend design between authentication and the
existing capability graph. It specifies route-level enforcement, target
resolution, groups, and the `/g/` namespace. Authentication providers prove a
Principal; neither an OIDC/LDAP group nor an HTTP route grants authority by
itself.
## Request authorization pipeline
Every registered route has a static `RoutePolicy`. Authorization must not infer
authority from arbitrary URL substring matching.
```go
type RoutePolicy struct {
Name string
Methods map[string]MethodPolicy
Authentication AuthenticationPolicy // public, optional, principal, service
CSRF bool
}
type MethodPolicy struct {
Capability string // read, write, rename, delete, link, manage, delegate
Resolve TargetResolver
}
type AuthorizationTarget struct {
DomainUUID string
Type string // domain, quartier, street, spot, path, object, group
ID string // canonical UUID where one exists
}
```
The request sequence is fixed:
1. Normalize the request and attach a request ID.
2. Resolve the local Domain from the effective host. Reject remote placement.
3. Match a registered route and method. An unregistered method returns `405`.
4. Resolve credentials into an optional Principal or a service/delegation
context. Domain browser sessions and Bearer tokens use the same stored
session record; adapter, federation, and future share tokens are distinct
credential types and are never promoted to Principal sessions.
5. Guard browser mutations with same-origin Fetch Metadata/Origin before any
authorization bypass. Cookie requests missing that evidence require a
matching Referer; otherwise deny. Explicit Bearer/service clients may omit
browser metadata, but actual cross-origin requests are still rejected. See
[browser request boundaries](browser-request-security.md).
6. Resolve the target without performing the operation. Path input is
normalized and resolved in the current Domain; Object and Revision routes
resolve back to their owning Object and all currently relevant bindings.
7. Evaluate Principal state, Domain membership, direct Role bindings, group
Role bindings, and positive grants. No match means deny.
8. Invoke the handler only after authorization. Record sensitive allows,
administrative mutations, and all denies in `auth_audit_log`.
Target resolvers return `404` only after the caller has enough `read` authority
to distinguish absence. Otherwise they return `403`, preventing private-object
enumeration. Authentication failures are `401` JSON for APIs and a login
redirect for browser navigation. Authorization failures are `403` in both.
For a path, candidate grants are the exact Object/Path exceptional grant, its
Spot/Street/Quartier ancestry once ZoneTree exists, and finally the Domain.
Evaluation stops at no artificial path segment: only stored topology records
participate. Until those locality records exist, the safe fallback is the
Domain grant plus exact Object/Path grants, not string-prefix inheritance.
An Object with several semantic bindings is readable through its UUID when an
exact Object grant applies or at least one live binding is readable. Responses
then include only bindings separately readable by the caller. A Revision and
its raw/derived projections inherit this Object decision; knowing a Revision
UUID never supplies authority. Broad Domain grants require a live local binding
or recorded creation provenance while the Object has no bindings anywhere.
Other unbound/foreign-only Objects require an exact Object grant, never a broad
Domain or Object-wildcard grant. See [Object authority scope](object-authority-scope.md).
## Route policy inventory
The first implementation slice uses the following policies. A more specific
locality target replaces `domain` as Quartier, Street, and Spot records become
available.
| Surface | Methods | Authentication | Capability and target |
| --- | --- | --- | --- |
| `/health`, static theme/CSS needed by login | GET/HEAD | public | none; health exposes no internals |
| `/_/auth/login`, setup, OIDC callback, magic-link request/verify | declared flow methods | public challenge | rate-limited, challenge-bound |
| `/_/auth/logout` | GET/HEAD confirmation; POST revocation | principal | revoke the supplied session only; browser origin guard |
| `/u/{username}`, `/g/{group}` and semantic Viewer paths | GET/HEAD | optional in legacy, principal in enforcing | `read` resolved path/domain |
| `/e/-/...`, `/:/new`, upload and compile write surfaces | GET plus declared writes | principal | `write` resolved path/locality |
| `/o/uuid:*`, `/o/path:*`, `/r/view/*`, `/r/history/*`, `/r/diff/*` | GET/HEAD | policy-dependent principal | `read` owning object/path; immutable IDs do not bypass policy |
| `/v/raw/*`, previews, archive/email/PDF children | GET/HEAD | policy-dependent principal | `read` source object/revision; cached derivations inherit source policy |
| `/v/search`, tree, browser and children | GET/HEAD | optional/principal | filter every result by `read`; never reveal hidden counts or ancestors |
| `/l/uuid:*` | GET | principal | `read`; POST/DELETE require `link` on object and affected paths |
| object/revision/tag APIs | exact route method | principal | list/read=`read`, create/save/tag=`write`, restore=`write`, purge=`delete` |
| path bind/copy/rename/remove APIs | POST | principal | `link`, `write`, `rename`, or `delete` on both source and destination as applicable |
| GC zombie list/purge | GET/POST | principal | Domain `manage` |
| `/-/sys/config*`, auth administration | GET/POST | principal | Domain `manage`; provider secrets never returned |
| event scheduler and queue APIs | GET or mutation method | principal | GET Domain `manage`; mutation Domain `manage` |
| adapter registry/open-with | GET/POST | principal | read source plus Domain `manage` for registry mutation |
| adapter session exchange/read/write | declared ticket | service | ticket scope, object UUID, base Revision, method, expiry, one use |
| federation enrollment | POST | service | Campus enrollment token, rate limit, controller mode; not Domain RBAC |
| future `/s/*` | GET/HEAD | delegated | macaroon caveats and underlying still-valid delegated grant |
Handlers must declare supported methods; a mutating operation is never exposed
through GET. Search indexes, recent-object lists, children projection caches,
preview caches, archive entries, and adapter workspaces are derived data and
must apply the source object's current authorization on every read.
The server keeps these declarations in a central typed endpoint policy
classifier. Exact API routes are method-closed, unknown mutations below a
reserved namespace fail closed, and semantic Page mutations use a Path target.
Handler-local checks remain authoritative where the target is carried in JSON,
multipart data, or an adapter ticket; those checks must be replaced only by a
typed target resolver with equivalent source and destination coverage.
For immutable addresses, authorization resolves back to mutable authority:
a Revision is authorized through its Object, and an Object is readable through
an exact Object grant or at least one readable live Path binding in the current
Domain. Raw bytes, bounded text, generated PDF pages, cached thumbnails, print,
history, and diff projections all reuse that decision. Their responses use
private caches varying on credentials even when the underlying Revision is
content-addressed. Directory/search projections authorize their requested scope
and filter every returned Path; hidden entries are excluded from displayed
counts.
Recursive namespace mutations expand the complete stored source set before the
transaction. Rename requires `rename` on every source and `create` on every
mapped destination; copy requires `read` and `create` respectively; recursive
delete requires `delete` on every affected Path. Link management additionally
requires `link` authority on the Object and affected Path, and only readable
bindings are returned by its UI.
## Content permission profiles
The group UI exposes profiles rather than ambiguous collections of checkboxes:
| Profile | Effective capabilities | Explicit exclusions |
| --- | --- | --- |
| `read` | `read` | every mutation |
| `read_write_once` | `read`, `create`, `upload` for a previously absent target | overwrite, later Revision save, rename, unlink, delete |
| `read_write` | `read`, `create`, `upload`, `write`, `rename`, `link` | delete |
| `upload_only` | `upload` for a previously absent target | list/read, overwrite, rename, unlink, delete |
`write` implies `create` and `upload` for canonical direct Role grants, while a
group profile stores its exact set above. `create` means create a new semantic
binding/Object and its first Revision. `upload` is checked only after the final
filename and destination path are normalized. Both fail closed if the target
already exists unless `write` is also granted. Deletion is never inferred from
write and requires an explicit `delete` grant outside these four profiles.
`group admin` and `group user` are membership administration roles, not content
profiles. Owner and manager are presented as group-admin variants; member is
presented as group user. Their Wiki access still comes only from a content
permission profile or another Role binding.
## Group model
A Pages group is a Domain-scoped collection of Domain memberships. It is not an
authentication provider group, a Role, a Capability, a Campus object, or a
semantic path. The group UUID is stable while its name and Wiki binding may
change.
```sql
CREATE TABLE groups (
uuid TEXT PRIMARY KEY,
domain_uuid TEXT NOT NULL,
name TEXT NOT NULL,
display_name TEXT NOT NULL DEFAULT '',
description TEXT NOT NULL DEFAULT '',
visibility TEXT NOT NULL DEFAULT 'members', -- public, domain, members
state TEXT NOT NULL DEFAULT 'active', -- active, readonly, archived
created_at_ms INTEGER NOT NULL,
updated_at_ms INTEGER NOT NULL,
UNIQUE(domain_uuid, name)
);
CREATE TABLE group_members (
group_uuid TEXT NOT NULL,
membership_uuid TEXT NOT NULL,
member_role TEXT NOT NULL DEFAULT 'member', -- owner, manager, member
source TEXT NOT NULL DEFAULT 'local', -- local or mapping UUID
created_at_ms INTEGER NOT NULL,
PRIMARY KEY(group_uuid, membership_uuid)
);
CREATE TABLE auth_group_role_bindings (
group_uuid TEXT NOT NULL,
role_uuid TEXT NOT NULL,
created_at_ms INTEGER NOT NULL,
PRIMARY KEY(group_uuid, role_uuid)
);
CREATE TABLE auth_group_mappings (
uuid TEXT PRIMARY KEY,
domain_uuid TEXT NOT NULL,
provider_type TEXT NOT NULL,
provider_uuid TEXT NOT NULL,
external_group TEXT NOT NULL,
group_uuid TEXT NOT NULL,
mode TEXT NOT NULL DEFAULT 'additive', -- additive or authoritative
enabled INTEGER NOT NULL DEFAULT 1,
UNIQUE(domain_uuid, provider_type, provider_uuid, external_group)
);
```
Names use `^[a-z0-9][a-z0-9_-]{1,63}$`; dots and the reserved names `_`, `new`,
and `sys` are rejected. Display names are unrestricted presentation metadata.
Initial implementation permits direct Principal membership only. Nested groups
are deliberately deferred to avoid membership cycles and unclear ownership.
Deleting a group is a soft archive followed by explicit purge. Archive removes
effective group Role bindings immediately but retains audit history and its Wiki
objects. Purge requires Domain `manage`, fails while bindings/mappings remain,
and never deletes Wiki Objects or Revisions implicitly.
### Effective capabilities
The evaluator unions positive grants from:
```text
Domain membership -> direct Role bindings -> grants
Domain membership -> group membership -> group Role bindings -> grants
```
Then it applies Principal, Domain membership, group, and Role lifecycle state.
There are no negative group grants. A Principal who belongs to the same Role
both directly and through groups receives one effective grant. Cache keys include
`domain_uuid`, `principal_uuid`, and a monotonically increasing policy version;
membership, binding, role, grant, or state mutation increments that version.
`owner`, `manager`, and `member` in `group_members.member_role` govern group
administration only:
- owner: metadata, managers/members, Role bindings, external mappings, archive;
- manager: metadata and member list, but not owners, Role bindings, or mappings;
- member: view the group according to visibility and use granted Roles.
Domain `manage` bypasses group-administration roles. Group ownership itself does
not imply Wiki `read` or `write`; those remain capabilities. At least one local
owner must remain while a group is active.
Group `visibility` controls only profile metadata and discoverability. `public`
does not make the group Wiki public, `domain` does not grant Wiki `read`, and
`members` does not make every member a Wiki editor. The normal capability
decision always protects the Wiki subtree.
## `/g/` user interface namespace
`/g/` is reserved before the semantic Viewer catch-all, parallel to `/u/`:
| Route | Purpose | Required authority |
| --- | --- | --- |
| `/g/{groupname}` | Group profile followed by the group Wiki root document | visibility plus Wiki `read` |
| `/g/{groupname}/_/edit` | Metadata, owners/managers/members, Role bindings and mappings | group manager/owner or Domain `manage` |
| `/g/{groupname}/_/avatar` | Mutable non-revision group image | GET by visibility; PUT/POST owner/manager |
| `/g/{groupname}/...` | Ordinary group Wiki semantic subtree | normal path capability |
| `/e/-/g/{groupname}/...` | Canonical editor route for group Wiki documents | normal `write` capability |
The reserved `/_/` segment is intercepted only immediately below the group
name. It never creates semantic children named `_`. `/g/` is excluded from the
normal root `children` projection just as `/u/` is; group discovery is provided
by an explicit group directory UI subject to group visibility.
The profile shell and Wiki document are separate projections. Absence of a Wiki
root document does not make the group absent. Renaming a group changes its
`/g/{name}` binding transactionally, preserves the group UUID and Objects, and
leaves an optional time-bounded redirect alias. It must check destination path
conflicts before mutation.
## Group API
HTML forms call versioned JSON endpoints; handlers may render errors for normal
browser submission but share the same service layer.
| Endpoint | Methods | Operation |
| --- | --- | --- |
| `/_/api/v1/groups` | GET, POST | visible group list; create group |
| `/_/api/v1/groups/{uuid}` | GET, PATCH, DELETE | detail; metadata/state; archive |
| `/_/api/v1/groups/{uuid}/members` | GET, POST | list; add Domain membership |
| `/_/api/v1/groups/{uuid}/members/{membership_uuid}` | PATCH, DELETE | change administrative role; remove |
| `/_/api/v1/groups/{uuid}/roles` | GET, PUT, DELETE | effective Role bindings |
| `/_/api/v1/groups/{uuid}/mappings` | GET, POST, DELETE | external group mappings |
All mutations require CSRF for cookie sessions, use optimistic `updated_at_ms`
or an ETag, and append actor, request ID, old/new values, and outcome to the
audit log. Bulk membership updates are transactional and bounded. List APIs use
cursor pagination and do not disclose invisible groups.
## Implementation boundaries
Route policies live beside route registration in `internal/server/routes` so a
new handler cannot silently inherit a broad default. Startup validates that
every non-catch-all route has policies for every accepted method. Typed target
resolvers live in `internal/server/authorization_targets.go`; they perform only
bounded reads. `internal/store/authorization.go` owns the effective direct and
group grant query, while `internal/store/groups.go` owns transactional group
mutations. HTTP handlers do not issue authorization SQL directly.
The semantic Viewer catch-all has one explicit policy whose resolver uses the
normalized semantic path. Reserved `/u/` and `/g/` handlers are registered
before it and delegate their Wiki descendants back to that same semantic
service after resolving the profile shell.
Minimum audit events are `auth.login.*`, `authz.denied`, `role.binding.*`,
`grant.*`, `group.created`, `group.updated`, `group.member.*`,
`group.role_binding.*`, `group.mapping.*`, and `group.archived`. Details contain
stable UUIDs and changed field names, but never passwords, provider secrets,
TOTP seeds, session/challenge tokens, email magic links, or raw OIDC tokens.
Required integration tests enumerate every registered route/method in the
policy registry and cover anonymous, authenticated-but-ungranted, direct Role,
group Role, readonly, suspended, cross-Domain, cookie-without-CSRF, Bearer,
service-ticket, renamed-path, multiple-binding, and derived-cache access.
## External group synchronization
OIDC/LDAP claims are normalized attributes, then matched only against explicit
`auth_group_mappings`. No mapping means no change. `additive` adds mapped
memberships but never removes local membership. `authoritative` may remove only
memberships previously created by that same mapping UUID; it cannot remove a
local owner or membership from another source. Every synchronization is audited.
OIDC synchronization occurs after successful subject verification and before
session issuance. Existing sessions observe policy-version changes on their next
request. Controller-managed Campus manifests may distribute provider metadata
and mapping definitions, but client/bind/SMTP secrets and live group membership
are not federated unless a future signed policy explicitly says so.
## Built-in administrator groups
Every Domain has reserved `campus_admin` and `domain_admin` groups. They cannot
be created, renamed, archived, or repurposed as ordinary groups. Existing owner
or Domain-manage bindings seed both groups during migration to avoid lockout.
- `campus_admin` controls Campus records and tokens, Domain creation,
placement, update, and deletion for that Campus. It has an owner-controlled
option to project its membership into every Domain belonging to the Campus.
- `domain_admin` controls Domain-local configuration, accounts, sessions,
groups, Roles, and grants. Only a `domain_admin` may create an ordinary
group. It is never inherited merely because two Domains share a Campus.
- ordinary group admins control only their own group and cannot grant
themselves either built-in administrative membership.
Campus projection records each independent origin in `campus_admin_grants`;
`group_members` is its strongest-role projection. Disabling inheritance or
removing a source revokes derived grants transactionally, without promoting
inherited entries into new roots. New projection-owned Domain memberships are
removed, and their sessions revoked, after the last source disappears unless
an independent group/role grant has adopted that membership. Local and other
inherited sources are preserved. Legacy memberships with unknown provenance
remain inert rather than being guessed to be safe to delete. See
[Campus administrator revocation](campus-admin-revocation.md) for the migration
boundary, transaction hooks, regression coverage, and remaining protocol work.
## Cross-Domain identity inheritance
Cross-instance inheritance uses a Domain-pair PSK, not a browser session or a
Campus enrollment token. The source stores only the PSK hash; the receiver
stores the PSK encrypted by its instance authentication key. A peer record pins
source/target Domain UUIDs, source FQDN, instance fingerprint, enabled datasets,
and last successful sequence. TLS remains mandatory except for an explicitly
named development-only HTTP setup path.
The signed snapshot/delta contains Principal UUID plus non-secret profile
metadata, stable external identities, groups, administrative membership role,
and content permission profiles. It never contains password verifiers, TOTP
seeds, recovery codes, sessions, challenges, provider client secrets, SMTP
credentials, avatars unless separately enabled, or audit-log secrets.
Imported rows retain `(source_instance_fingerprint, source_domain_uuid,
source_uuid)` as their stable key. Local UUIDs remain local. Each imported
membership records its peer UUID as source, so disabling a peer removes only
that peer's effective membership. Groups with the same display/name but a
different source identity are not merged implicitly.
The receiver pulls monotonically sequenced deltas and applies each sequence in
one transaction. Replay is idempotent; gaps trigger a full snapshot. A changed
source fingerprint stops synchronization and emits a warning until a Campus
administrator approves the replacement. `campus_admin` may opt into fan-out to
all Domains in its Campus; `domain_admin` and ordinary groups are inherited only
when explicitly selected by the peer policy.
## Migration and implementation slices
1. Replace `requestedCapability` with route policy registration, exact methods,
typed target resolvers, and deny/audit tests. Preserve `legacy` only for
semantic read routes; administration and mutation are never anonymous.
2. Add CSRF for cookie mutations and separate Principal, adapter, federation,
and future delegation credential resolvers.
3. Add group schema/service, `/g/` routing, profile/edit UI, and i18n. Migrate no
existing Role binding destructively; group Role bindings use a new table.
4. Extend effective authorization with group bindings and policy-version cache;
add direct/group union and state-invalidation tests.
5. Add external group mapping and audited OIDC/LDAP group synchronization. LDAP
authentication is implemented; directory-group lookup and explicit mapping
reconciliation remain separate authorization work and must not be inferred
from the successful login attributes.
6. Switch new Domains to enforcing after owner bootstrap; retire the broad
`legacy` bypass only after the endpoint matrix has integration coverage.
Rollback disables group-derived evaluation and route-policy enforcement behind
separate migration flags; additive tables remain readable. It never drops
Principals, sessions, existing direct Role bindings, Objects, or Revisions.
+70
View File
@@ -0,0 +1,70 @@
# Scoped automatic publication
Implemented 2026-09-19. Explicit opt-in, local Domain policy; no existing scope is
enabled by migration or deployment. This is a live-head publication mechanism,
not the reviewer/Inbox workflow in `publication-approval-inbox.md`.
## Scope and controls
- City detail → governance dialog → Automatic publication → preview current impact.
- `inherit`: no local automatic rule; ancestor automatic rules may apply.
- `required`: manual publication only, including descendants. A descendant cannot
override this floor by selecting automatic. Supported at Domain/Quartier/Street/Spot.
- `automatic`: supported only at Street/Spot, with an effective public audience.
Existing eligible Pages, future descendants (including moved-in Pages) and all
current language heads are public immediately. Empty scopes can opt in too.
- Existing public audience ceilings and user/group restrictions remain authoritative.
Aliased Objects, reserved Paths and restricted descendant scopes remain excluded.
- Automatic and inherited activation require confirmation of current impact and
future publication. Preview binds actor/scope/governance/topology and all automatic
rule versions. CAS plus SQLite writer reservation reject stale or concurrent edits.
- Stopping automatic publication does not revoke separately frozen approvals. Use
audience restriction for complete privacy. Existing publication-revoke also sets
this scope to manual-only to stop automatic publication inherited from an ancestor.
## Authority, data and read behavior
`locality_auto_publication` stores Domain, node kind/UUID, mode, pinned Path boundary,
enabling Principal and version. The enabling Principal must remain an active member
with current governance and scoped read authority. Existing owner/admin delegation
is reused; ownership, membership and role revocation suspend the corresponding grant.
Audit records use `city_governance_events`; no silent new grants or source-content edits.
Automatic publication uses a read transaction, not materialized approval entries or
an asynchronous job. This gives read-after-write publication for authorized posts,
CLI writes and edits without a stale scheduler window. Anonymous body/raw reads,
public navigation, projected blog/diary titles, RSS and share readiness use the same
rules. Manual exact-Revision approvals remain the default and remain separate.
The boundary is pinned to the configured Path; renaming the Street/Spot boundary
suspends its grant until explicitly reconfirmed. Moving a Page outside the boundary
does not carry publication with its UUID. Audience restrictions are checked live.
Domain/Campus disablement and authorization-mode changes fail closed. Enforcing
authorization cannot be switched off while an automatic rule remains configured.
Public-navigation generations include automatic rules and their authority sources.
Role/member invalidation is conditional on the existence of automatic rules, keeping
the existing invariant that ordinary authenticated navigation never caches ACLs.
## API and budgets
`GET/PATCH /_/api/v1/city/{zones|spots|domains}/{uuid}/governance/auto-publication`
uses the existing authenticated handler-owned governance authorization. PATCH fields:
`mode`, `version`, `epoch`, `topology_version`, `confirm`, `impact_token`.
GET never grants publication. Strict JSON and 4KiB input limits apply.
Impact previews retain the existing 512-Path limit; a too-large preview still permits
manual-only shutdown, but not activation. Live navigation is metadata-only and bounded
by 20,000 entries / 4MiB with a 2-second caller deadline. Exact body lookup restricts
the query to the requested Path. Policy enumeration is capped at 128 local rows.
Errors/budget exhaustion do not fall back to public/unfiltered content.
## Remaining work
- Independent reviewer policies, requests, quorum, Inbox and signed Campus inheritance.
A future `approval=required` floor must also block this live-head publication mode.
- Federation of these policies is not implemented; no automatic-policy fields are
added to Domain provisioning manifests.
- Larger activation previews need paginated impact review/token binding rather than
silently lifting the current limit. Policy tombstone/archived-node cleanup is pending.
- External caches, feed-reader copies and already-posted social links cannot be recalled.
+91
View File
@@ -0,0 +1,91 @@
# Browser request and session boundaries
Implemented 2026-09-14. All requests pass the browser mutation guard before
authorization's legacy-mode or handler-owned route branches. Same-origin forms
and fetch calls continue working without page-specific hidden-token injection.
## CSRF
The guard uses Go's `http.CrossOriginProtection` (available since Go 1.25) and
has no trusted cross-origin list or route-prefix exceptions. Fetch Metadata and
Origin distinguish same-origin requests from unrelated or sibling origins;
`Origin: null` is rejected. Host resolution never trusts `X-Forwarded-Host`.
For legacy clients without same-origin Fetch Metadata, Origin must also use the
request's scheme; an HTTP origin cannot target an HTTPS browser session merely
because the host matches. TLS-terminating proxies must preserve forwarded scheme.
See the [Go 1.25 HTTP release notes](https://go.dev/doc/go1.25#net/http).
Unsafe requests carrying an ambient session/MFA cookie must additionally have
validated origin metadata or a matching HTTP(S) Referer. Missing browser-origin
evidence fails closed. Headerless server-to-server clients remain supported;
API clients should use explicit Bearer authentication. Cross-origin login,
profile/group/configuration/upload and API mutations are covered, not just
document save routes. API denials return JSON with status 403.
Logout is POST-only for revocation; GET/HEAD render confirmation without
changing session state. Profile menus submit a native same-origin POST form.
Bearer logout revokes exactly the supplied token, not an unrelated cookie.
Legacy semantic editor GET entry can still allocate an empty Page. Its entry
routes are therefore checked as mutations too; direct address-bar/bookmark
navigation with browser `Sec-Fetch-Site: none` remains allowed. Moving creation
fully into the save transaction remains a separate editor API correction.
OIDC/magic-link callbacks are one-use, purpose-bound login flows, not generic
state-changing GET endpoints. OIDC additionally has browser-bound state.
## Credential purpose
New API tokens begin with `pw_api_`; new cookie sessions begin with
`pw_browser_`. The complete prefix plus random secret is SHA-256 hashed in the
session store. Changing/removing a prefix cannot convert its purpose.
Browser tokens are rejected in Authorization; API tokens are rejected in the
session cookie. Adapter/federation/challenge tokens use independent validation
and tables and are not accepted as login sessions.
Unprefixed pre-upgrade sessions retain compatibility until their recorded
expiry (normally 24 hours). No live session is forcibly migrated or broadened.
Once the old rows expire, new sessions enforce transport separation throughout.
Store helpers without HTTP context remain trusted internal APIs.
Session insertion itself requires an active/readonly Principal and active Domain
membership in the same SQL statement. Each session lookup rechecks membership;
disabling/removing it invalidates the next request even if a session row remains.
Dynamic responses default to `private, no-store` with credential variation;
individual immutable projections can opt into a specific private cache policy.
An explicitly supplied invalid/unknown/ambiguous Authorization header never
falls back to a cookie. Duplicate session cookies are rejected. Login body
size and local return URLs are validated; slash/backslash/control-character
redirect variants cannot redirect to another authority.
## Request-scoped read authorization
Domain lookup is cached only in one request. A bounded single-query snapshot
loads at most 4096 direct-role/group Path read grants, honoring principal and
membership states, exact direct grants and literal group subtree boundaries.
It is immutable, contains no list of all document Paths and is discarded at
request end. Errors/oversized policies fail closed. Tree/children/search/City
read filtering reuses this snapshot; mutation authorization does not.
The next request rechecks sessions, membership and grants. There is no TTL
allow-cache that outlives revocation. A change during an already-rendering
request takes effect on the next request; transactional mutation authorization
and streaming revocation have separate contracts.
## City projection
Map/detail/Spot Page APIs, City macros and Viewer locality badges filter by
readable locality boundaries and Page Paths. Counts and portal choices are
recomputed from visible Pages; nearby relations require both visible ends.
No Domain-only topology ETag is reused across callers (`private, no-store`).
Parents without readable boundaries are not exposed just because a descendant
or MagicPage happens to be readable. Unbound/hidden aliases are not substituted
with UUID links to bypass Path visibility. The complete topology is still loaded
before projection; lazy server-side City pagination remains outstanding.
Regression tests cover cross-origin/missing-metadata denials, login/logout,
purpose confusion, exact/wildcard grant semantics, principal states, next-request
revocation, hidden City metadata/counts/portals/relations and macro projection.
An opt-in Chromium regression additionally submits the real login and logout
forms using HttpOnly cookies and actual Fetch Metadata, with no injected Bearer
credential, and verifies logout leaves a separate API session intact.
+99
View File
@@ -0,0 +1,99 @@
# Campus administrator inheritance: revocation and provenance
Implemented: 2026-09-14. This note supersedes the former insert-only Campus
projection described in `authorization-groups.md`. Cross-instance Domain-pair
PSK synchronization is still a separate, unimplemented protocol.
## Authority and data ownership
`campus_admin_grants` is the authoritative set of independent and inherited
grants for the built-in `campus_admin` group only. Its key is
`(group_uuid, membership_uuid, source)`. An independent grant uses `local`,
`migration`, or an existing non-Campus source identifier. Derived grants use
`campus_admin_inherit:<origin group UUID>`.
`group_members` remains the public/effective membership table. The strongest
remaining role wins (`owner > manager > member`), with a direct source winning
ties. A weaker local grant is kept in provenance, not overwritten by a stronger
inherited role, and becomes effective again when that inherited role expires.
Ordinary groups and `domain_admin` retain their existing storage and behavior.
Projection roots must have an active source group, active principal, active
source Domain membership, enabled source Domain, and enabled inheritance flag.
The target must be an enabled Domain in the same Campus with an active built-in
group. Only independent grants are roots. Derived rows cannot retransmit
authority, become new roots, or keep one another alive in a cycle. Multiple
independent origins are recorded separately; removing one does not remove the
others. Changing a principal to readonly also withdraws inherited administrator
membership; changing it back to active can restore the projection but does not
revive revoked sessions.
## Transaction boundary
The following write paths reconcile within the same SQLite transaction:
- enabling/disabling Campus inheritance;
- adding, changing, or removing an independent Campus group member;
- changing a principal's state and revoking its sessions;
- updating/deleting a Domain, including moves between Campuses;
- applying a managed-Campus topology snapshot or deleting a managed Campus;
- built-in group creation/bootstrap migration.
The projection rebuilds the effective Campus group membership from authoritative
grants. Any SQL failure rolls back both the source mutation and the projection.
No asynchronous queue or stale authorization cache sits between revocation and
the next authorization decision. Direct SQL administration must explicitly run
`ProjectCampusAdminMemberships`; deleting only the materialized `group_members`
row is not a revocation API. Future LDAP/OIDC mappings and PSK importers must
write provenance and reconcile in their own transaction, not edit the cache.
Inherited-only members cannot be removed at a destination: revoke their origin
or disable its inheritance. Removing an independent owner requires another
independent owner at that source; an owner inherited from somewhere else is
not sufficient. Bootstrap migration records each migrated source binding once
in `campus_admin_migrations`, so a later explicit Campus-group removal is not
undone by a restart or the creation of another Domain.
## Domain membership and session cleanup
`campus_admin_membership_origins` records exactly which Domain memberships the
projector created. After the last derived grant disappears, a provenance-owned
membership with no other group membership or role binding is removed and that
principal's sessions in that Domain are revoked atomically.
Existing local memberships are never reactivated, relabeled as inherited, or
deleted by projection. Adding an independent group grant adopts an inherited
membership as local. An independent role binding likewise prevents cleanup and
preserves its session. No role binding or capability grant is deleted: the old
Campus projection never created `auth_role_bindings`, and revocation of a group
membership already removes access through that group's permission profiles.
Independent `domain_admin` and direct role capabilities remain unchanged.
## Upgrade behavior and limits
Older installations recorded only one source per effective group member and
did not record the origin of a Domain membership. On the first schema upgrade,
only stored non-inherited Campus group memberships seed authoritative grants;
old inherited chains are discarded and regenerated from those roots. A legacy
Domain membership with ambiguous origin is retained, while its inherited group
authority is revoked normally. Do not guess that an untagged membership belongs
to the projector and delete a potentially independent local identity record.
An old local grant previously overwritten or mislabeled by the single-source
implementation cannot be reconstructed; an administrator must explicitly grant
that local role again if needed. Newly recorded grants do not have this loss.
Reconciliation is set-based and limited to Campus administrator memberships;
it runs on administrative changes, not on ordinary reads or session lookups.
It currently recomputes all Campus administrator projections in one transaction.
Incremental Campus-scoped reconciliation and sequenced cross-instance deltas are
future scaling work; do not advertise distributed revocation guarantees before
the PSK protocol and its source-disappearance policy exist.
## Regression coverage
`groups_inheritance_test.go` covers disable/re-enable, repeated reconciliation,
source removal, suspension/quarantine/readonly, removed/disabled/moved source
Domains, multiple roots, prevention of transitive amplification, weaker local
role restoration, independent role/session preservation, legacy-chain cleanup,
restart-safe bootstrap removal, and injected mid-transaction failures for
disable/remove/suspend. Existing concurrent owner-integrity tests remain green.
+99
View File
@@ -0,0 +1,99 @@
# Campus and Domain Model
## Purpose
Campus is the top-level administrative and language-default boundary.
Domain is the host-selected subdomain space presented to a request. Every
Domain belongs to exactly one Campus.
This slice intentionally stops before ZoneTree. Quartier, Street, Spot, and
SpotGraph remain later topology work.
## Identity
Both Campus and Domain have:
- an integer SQLite row ID for local administration;
- a stable UUID for relationships;
- a normalized, unique machine name;
- a human-readable title;
- an enabled flag;
- a creation timestamp.
Campus additionally has a BCP 47 default language, authority mode, and FQDN.
Domain additionally has a host selector. A selector can be a full host
(`docs.example.test`), a subdomain label (`docs`), or empty to select the
Campus FQDN itself.
## Ownership invariants
- Every Domain `campus_uuid` resolves to an existing Campus.
- At least one Campus exists and at least one Campus remains enabled.
- A Campus referenced by a Domain cannot be deleted.
- A Campus referenced by a Domain cannot be disabled.
- Creating or moving a Domain requires an enabled target Campus.
- Disabled Domains do not participate in request-host selection.
- Request-host resolution is exact and has no last-resort Domain fallback.
- An empty Domain host matches only its owning Campus FQDN.
- The request Campus is derived from the resolved Domain; it is not selected
independently.
SQLite does not currently rebuild legacy tables to add a foreign-key
constraint. These invariants are enforced by store operations so existing
installations can migrate without destructive table replacement.
## Schema
```sql
CREATE TABLE campuses (
id INTEGER PRIMARY KEY AUTOINCREMENT,
uuid TEXT NOT NULL UNIQUE,
name TEXT NOT NULL UNIQUE,
title TEXT NOT NULL,
default_lang TEXT NOT NULL DEFAULT 'en',
authority_mode TEXT NOT NULL DEFAULT 'standalone',
fqdn TEXT NOT NULL,
enabled INTEGER NOT NULL DEFAULT 1,
created_at INTEGER NOT NULL
);
-- Added to domains during initialization:
ALTER TABLE domains ADD COLUMN campus_uuid TEXT;
CREATE INDEX idx_domains_campus_uuid ON domains(campus_uuid);
```
## Startup migration
Initialization is idempotent:
1. The existing District-to-Domain compatibility migration runs.
2. If no Campus exists, `Default Campus` is created.
3. The nullable `domains.campus_uuid` column is added when absent.
4. Empty, unknown, and legacy Campus references are assigned to the enabled
default Campus.
UUIDs, Domain host selectors, and existing paths are preserved.
## Request context
The server resolves one Domain from the HTTP Host and then resolves its
owning Campus. Both values are exposed as `RequestContext.Domain` and
`RequestContext.Campus`.
Revision language selection uses this order:
1. explicit language request;
2. request language preferences;
3. Campus default language;
4. system locale;
5. language-neutral revision;
6. latest revision.
## Administration
The Config view supports Campus create, update, and delete, as well as Domain
assignment to a Campus. The last enabled Campus cannot be disabled. A Campus
must first have its Domains moved or deleted before it can be deleted.
The data CLI remains object/path/revision/asset oriented. Campus and Domain
administration is therefore not added to the CLI in this slice.
+93
View File
@@ -0,0 +1,93 @@
# City courtyard projection and immersive navigation
Implemented UI slice, 2026-09-14. Complements
[City organization](city-organization-ui.md) and the larger
[City review](city-review-and-reconciliation.md); not a replacement for its
authorization, reconciliation or Worker hardening work.
## Interaction
The browsing sequence is `Domain → Quartier → Street → Spot → Page`.
Clicking a Spot now explores its courtyard **inside the map**, rather than
immediately navigating to its portal document. The central building represents
the Spot; surrounding smaller buildings are its Page placements. The focused
Spot offers a separate portal Page link. An actual boundary/portal Page is not
repeated as its own surrounding Page building. A descendant suggested by the
API as a fallback portal remains independently visible/selectable. Undefined
placements use a fountain and retain
yellow-green Page markers.
Page buildings link to their semantic Path, falling back to `/o/uuid:{uuid}`.
These are rendering changes only: no document Paths, memberships, UUIDs,
revisions or contents are changed. The displayed set follows existing SpotGraph
membership, including explicit links; it is not a new filesystem hierarchy.
Breadcrumbs and clicking outside the courtyard ascend within the map. Map
exploration does not call pushState or add browsing history. Actual Page links
still navigate normally (from a map popup, in the containing window).
Ctrl/Command selection and the existing merge/rename/move dialogs work for
whole Spots and individual Page buildings, without following their links.
## Layout and visual vocabulary
- Domain/Quartier retain the single generated city fabric and its allocations.
- Street close-ups use a deterministic courtyard layout, with generated road
segments projected behind it and paths connecting courtyard gates to roads.
This is a readable close-up schematic, not geometric continuity at every zoom
level. Connected road allocation and natural parcel packing remain future work.
- Nonoverlapping plots reserve space for the Spot, six nearby Pages and gates.
At most six Spots are rendered per Street screen; further Spots are paginated.
- A focused Spot renders at most 24 surrounding Pages per screen, also paginated.
Page UUID deduplication prevents multiple graph edges creating duplicate houses.
- Labels remain horizontal and visible at rest, with bounded two-line wrapping
and full-name/Path tooltips. The existing label toggle controls the new labels.
- Native SVG motifs include stucco/terracotta houses, a pediment and colonnade,
stone paving, balustrades, cypresses, fountains and ornamental iron gates.
Theme-derived stone/brass colors, the academic crest and compass carry the
same visual language into the map frame and menu. No external images/fonts
or raster-generation service are needed for these additions.
The new `city-estates.js` module owns only close-up layout and rendering.
`city-map.js` retains topology, navigation, generated fabric and API interaction;
`city-organizer.js` retains selection and mutations. The obsolete geometry
script and mutation-observer Spot repositioning no longer run on the map.
Pointer dragging and wheel zoom use SVG coordinates with a screen-pixel drag
threshold, including differently sized close-up viewBoxes.
## Utility menu
The initial normal and popup screens show the map, breadcrumb, menu launcher,
small navigation hint, compass and (only when needed) pagination/selection bar.
The permanent inspector, directory, planner and toolbar are moved into a themed
native modal (`city-menu.js`):
- Guide: selected locality, details link and existing editing operations.
- Directory: named navigation to Quartier/Street/Spot views.
- Planning, for authorized planners only: URL planning and one creation form at
a time, selected by kind.
- Settings: zoom/reset/labels, topology status, scoped search and account links.
The dialog uses native modal focus containment and Escape dismissal. Its Escape
handler does not propagate to the containing map popup. There is no permanent
outer-page scrolling; menu content can scroll independently. Mobile CSS reduces
the frame and changes the menu navigation to two columns.
## Verification and limits
Opt-in Chromium fixtures cover normal/popup modes: resting labels, Ctrl
selection, title/group/merge/move regression, plot nonoverlap, six-Spot and
24-Page bounds, full pagination reachability, correct Page/portal links,
unchanged map URL/history, menu panel switching, creation-form visibility,
directory navigation and background ascent. Screenshots cover sparse Street,
dense Spot and menu scenes, including a 390px viewport with Index White. Run:
```sh
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive)Chromium' -count=1
```
These are DOM-rendering bounds, **not** server/API pagination. The map still
loads topology and Page placements eagerly; the directory and some inspector
option lists still traverse that loaded topology. Per-result authorization,
bounded/lazy server projection, connected roads, Worker generation, keyboard
directional navigation and auto-reconciliation remain open in CITY-A–D.
This slice does not claim to solve those scaling/security gaps.
+81
View File
@@ -0,0 +1,81 @@
# City organization UI
Implemented follow-up, 2026-09-13. This is a bounded manual editing slice of
[the City review](city-review-and-reconciliation.md), not the automatic outbox
or Worker pipeline.
## User model
Hierarchy remains `Quartier → Street → Spot → Page`; a Spot cannot own a Spot.
Yellow-green points are unclassified Pages, not nested Spot objects.
- Context menu or inspector pencil: edit a locality's **display title**. UUID,
slug/name and Path remain unchanged. Japanese titles are accepted.
- Ctrl/Command-click toggles selection of Page buildings/points or whole Spots.
Selection persists while navigating between Streets. As of 2026-09-14, ordinary
Spot clicks explore a courtyard; Page buildings and the separate portal link
navigate to documents. See [immersive map projection](city-immersive-map.md).
- The floating icon toolbar/context menu can combine the selection into an
existing Spot, or create one Spot containing the selected Pages.
- Whole-Spot merge archives the sources, transfers Page placements and
incoming/outgoing relations, deduplicates relations and drops self-relations.
Source descriptions/charters remain on archived rows; they are not concatenated
into the destination. Existing destination labels take precedence over duplicates.
- Move relocates whole Spots to a Street, retaining UUIDs. Path boundaries
change atomically with Street placement. Single moves allow a custom boundary;
bulk moves use the old boundary's final segment under the new Street.
Conflicts or invalid ancestry reject the entire operation.
These operations **preserve document URLs, Page UUIDs, Revisions and content**.
Moving a Spot captures its existing inferred members as explicit memberships;
the moved boundary may infer new Pages too. This is a City/SpotGraph operation,
not recursive filesystem/URL rename. The modal explains the distinction before
submission. Changing document URLs remains a separate Path operation.
## Backend contract
- `POST /_/api/v1/city/{zones|spots}/{uuid}/title`: title and mandatory
`base_version`; zones additionally supply `kind=quartier|street`.
- `POST /_/api/v1/city/organize`: mandatory `base_version`, `action=merge|move`,
whole-Spot UUIDs and/or `{spot_uuid,page_uuid}` selections. Merge chooses
exactly one of `target_spot_uuid` and a `new_spot` definition. Move accepts
whole Spots and a destination Street only.
- Both routes require existing Domain administrator/manage authorization.
Targets, sources, parents and Page membership are revalidated inside the
transaction against the current Domain. Stale topology returns 409.
- Selection is limited to 200 entries. Expansion is capped at 2,000 Page-edge
placements and 2,000 affected relations; larger operations fail without
partial application. This is not a background bulk-import API.
- Transfer, archive/move, overrides and one topology event/version increment
commit together. Title no-ops do not increment versions. Validation/DB failures
roll back everything; retries using an old version cannot reapply.
- Audit events store requests, source placements and previous Path/Street
boundaries. No automatic undo UI or exact reverse-operation endpoint exists
yet; this is not a complete reversible merge implementation.
`city_page_overrides(domain_uuid,page_uuid,spot_uuid)` records manual placement.
Active overrides prevent autoplan reconstructing old assignments and suppress
inferred membership in other Spots. Other explicit MagicPage edges remain valid.
An archived destination no longer suppresses inference; overrides are carried
forward when its whole Spot is merged again. This is not the future full
generation-provenance/outbox design or a general exclusion-management UI.
Normal and popup views share a themed native modal and selection toolbar;
Ctrl/Command-click in a popup must not trigger top-window navigation.
The generator seed no longer includes topology version, and its in-page fabric
is reused on reload so renaming does not randomly rebuild the town. Allocation
can still change with membership weights; Worker generation and persistent
geometry caching remain open.
## Verification and remaining work
Store/API tests cover Unicode titles, identity/URL preservation, stale requests,
admin denial, invalid/cross-Domain selections, relation transfer/deduplication,
inference preservation, and rollback after injected mid-write failure.
Chromium tests exercise Ctrl selection/deselection, grouping undefined Pages,
rename, whole-Spot merge, relocation and autoplan overrides in normal/popup modes.
Remaining: editable slug aliases and redirects for merged Spot detail URLs;
per-Page override management/undo; URL-renaming with explicit preview;
bounded automatic reconciliation; projection authorization/read scaling;
Worker/geometry capacity fixes and directional keyboard navigation.
+91
View File
@@ -0,0 +1,91 @@
# Bounded City read snapshots and literal Path boundaries
Implemented 2026-09-14. This is a bounded repair of CITY-04/CITY-06, not completion
of the [City review](city-review-and-reconciliation.md) or its lazy projection plan.
## Read contract
`GetCityMapContext` uses one read-only SQLite transaction with a two-second
deadline, shortened by request cancellation. The topology version, Quartiers,
Streets, Spots, Page placements and relations all come from that same snapshot.
Each cursor is fully scanned, checked and closed before the next query; a
one-connection pool therefore works without nested-connection deadlock.
Quartiers, Streets, Spots and relations use four bulk cursors. Page placements
still use one bounded query per Spot, on the **same transaction/connection**.
Parent joins require current-Domain active Quartiers/Streets/Spots. Foreign or
archived parents cannot introduce children into the model. Explicit Page edges
require a current-Domain Path binding, including edges left behind after moving
the last binding to another Domain. Relations require two visible active Spots.
The projection fails with `ErrCityMapBudget` rather than silently truncating:
| Budget | Limit per complete map |
| --- | ---: |
| Quartier + Street + Spot nodes | 4,096 |
| Page placements, including multiple semantic appearances | 20,000 |
| Relations examined | 8,192 |
| Database snapshot / connection wait | 2 seconds |
Errors return an empty model, not partial topology with apparently successful
counts. Spot counts deduplicate Page UUIDs while preserving distinct typed edges.
Exact boundary Pages remain preferred portals. Query/scan/version errors are
propagated, and all error/cancellation paths release cursors and connections.
`ListSpotPagesContext` applies the same two-second read transaction and 20,000
placement safety limit to an HTTP Spot projection. Trusted `ListSpotPages`
retains its complete-set contract. This is a safety ceiling, **not pagination**.
No Page bodies or revision histories are read for these projections.
HTTP map/detail/Page projections return `503` with `Retry-After: 5` when a
safety ceiling or request deadline is reached, rather than misreporting a
large locality as missing. Missing or unreadable localities remain `404`;
unexpected storage failures remain `500`.
The server's separate request-scoped read-policy filter remains mandatory: a
consistent Domain snapshot is not authorization to see every locality or Page.
No cross-principal model cache or topology-only public ETag is introduced.
## Literal boundary contract
All SQL containment/overlap matching in `city.go` and `city_operations.go` uses
case-sensitive binary segment ranges, not `LIKE`. A normalized non-root boundary
`/a%_` contains its exact Path and the range `[/a%_/, /a%_0)`; `%`, `_`, backslash
and Unicode are ordinary characters. `/A` does not contain `/a`, and `/life`
does not contain `/life2`. An empty legacy boundary contains nothing.
Root `/` covers every absolute Path. Creating it therefore conflicts with any
other active Quartier boundary, regardless of creation order. Streets and Spots
still require strict descendant Paths and their existing valid parent/Domain.
No raw Path or UUID is changed, decoded again, lowercased or escaped in storage.
Creation validation, import overlap lookup, Path-context resolution, inferred
Page membership, appearance lookup and health checks use these semantics.
Context and health use bounded read snapshots too. The `/u` health exclusion
includes the namespace root and descendants, not unrelated or differently-cased
Paths. Health is still a basic topology summary, not a full reconciliation of
manual membership overrides and all curation semantics.
## Verification and remaining work
`city_read_test.go` covers a one-connection pool, WAL concurrent commits between
snapshot pinning and topology loading, all three size ceilings, connection-wait
cancellation, nested scan errors, connection release, foreign/archived parent
edges, foreign explicit Pages, literal wildcard/case/Unicode boundaries, root
overlap, and health/context/overlap consistency. Existing City/import/organizer
tests remain regression gates.
2026-09-14 named references: `/v/city/s/{quartier}/{street}` resolves in one
bounded query with its current active parent. Legacy unique Street names and
explicit `uuid:` references still work; ambiguous legacy references fail closed
with the same 404 as missing/hidden nodes. Details check ancestor read access,
do not load the map, and propagate cancellation. Breadcrumb macros defer map
loading until `nearby` actually needs it. Literal Page links encode `?/#/%`.
Regressions: `city_reference_test.go`, `city_links_test.go`, and Chromium
`city-links.js` (normal, popup and all three initial-focus levels).
Still pending: lazy paginated locality/Page APIs; removal of per-Spot Page
queries; size limits for individual legacy metadata fields; context propagation
to remaining health/macro callers; full URL-autoplan provenance/atomic adoption. Large City data
can currently exceed a safety ceiling and show an error until lazy projections
are implemented. Raising global limits is not a replacement for that work.
@@ -0,0 +1,261 @@
# City module review and URL-driven reconciliation
Reviewed: 2026-09-13; implementation follow-up 2026-09-14.
Status: **incremental repairs landed; automatic reconciliation remains design-only**.
Scope: City stores/APIs, URL autoplan, SVG UI, the bundled gen-city 1.4.6
adapter, and scheduler integration. This supplements
[Knowledge City Model](knowledge-city-model.md) and the
[platform outbox contract](platform-extension-architecture.md#event-and-outbox-contract).
Phase 2 checkboxes represent first slices, not completion of these repairs.
## Landed follow-ups
- [x] CITY-05 named-route slice: parent-qualified Streets, bounded cancellable
detail lookup with active same-Domain ancestors and ambiguity detection;
shared links across search, map, inspector, context menu and macros.
Detail views no longer load the whole City; map focus and locality search
support all three levels. Spot autoplan name collision handling remains open.
- [x] Per-result map/detail/Page/macro/badge authorization and private responses;
visible portal/count/relation recomputation.
- [x] One-connection-safe bounded City/Spot read transactions and binary literal
Path containment/overlap/context/health matching; see
[read integrity and remaining limits](city-read-integrity.md).
- [x] Stable Domain fabric seed, local Worker generation, bounded geometry cache,
deadline/cancellation and directional Arrow/WASD/HJKL navigation; see
[Worker contract](city-worker-navigation.md).
- [x] Horizontal/resting labels, manual organization, nonoverlapping bounded
Spot courtyards with Page buildings and a modal utility menu; see
[immersive projection](city-immersive-map.md).
Lazy Page APIs, connected road allocation, deterministic generated Spot names and the
outbox/provenance/idempotent inference pipeline are not implied by these checks.
## Original findings, in repair order
| ID / priority | Evidence at audit | Correction |
| --- | --- | --- |
| CITY-01 / P0 | `city_handler.go` returns `GetCityMap` and `ListSpotPages` without per-member authorization. Middleware gates the endpoint, not each returned Page/locality. | Batch-authorize nodes, Page links, portals, relations and counts. Audit details/macros too; Domain read must not expose denied descendants. |
| CITY-02 / P1 | `buildCityAutoPlan` ignores Paths shorter than three segments despite its UI's shallow-Page description. `AddSpotPage` increments topology version even on identical repeated UPSERTs. | Explicit root/portal/leaf rules and no-op reconciliation for unchanged inputs. Separate inferred membership from manual edges. |
| CITY-03 / P1 | POST `/city/autoplan` synchronously scans all Paths and applies separate node/edge transactions; the first error leaves a partially applied plan. No generation ownership/checkpoint exists. | Preview/adoption, bounded resumable batches, source provenance and itemized conflicts before automatic jobs. |
| CITY-04 / P1 | `CityNodeOverlappingPath` merges exact/ancestor/descendant candidates with `LIMIT 1`; it and `ListSpotPages` use unescaped LIKE patterns. Autoplan treats lookup errors as absence. | Literal normalized Path segments, compatible parent/identity matching, explicit ambiguity and DB errors. Test `%`, `_`, case and non-ASCII Paths. |
| CITY-05 / P1 | Streets allow repeated names under different parents but `CityNode`/detail URLs resolve by Domain/name. Spots require Domain-unique names, while autoplan derives only a URL segment. | Server-provided unambiguous hrefs, parent-qualified readable Street routes, existing UUID fallback, deterministic Spot name collision handling without altering display titles. |
| CITY-06 / P1 | `GetCityMap` nests open cursors and queries per Quartier/Street/Spot, returning every Spot's entire Page list. Autoplan also queries while the Paths cursor is open. No consistent read snapshot. | Bounded bulk queries, snapshots, closed cursors, cancellation and lazy locality/Page APIs. Test with a one-connection pool. |
| CITY-07 / P1 | `render()` seeds gen-city with `domain_uuid:topology_version` on every reload. Cached `city-geometry.js` output is assigned to `geometry` but never used by this renderer. | Stable base-fabric seed and one real geometry cache; remove obsolete generation after migration/tests. |
| CITY-08 / P1 | gen-city's `async generate()` runs synchronous matrix initialization, recursive path generation and building generation. Layout/SVG construction also runs on the main thread. | Worker generation/layout with cancellation and budgets; separately bound DOM work. `await` alone is not CPU isolation. |
| CITY-09 / P1 | `cityLayout` sorts/slices roads by coordinates, not connectivity; early Streets can consume all roads. Spots without buildings are omitted. Proximity uses infinite-line rather than segment distance. | Connected/fair allocation, finite segment projection and fallback picking targets. Geometry scarcity must never hide a logical node. |
| CITY-10 / P1 | Street weights sum Spot weights (duplicate Page counting), unlike Quartier weights. Allocation repeats on navigation; a MutationObserver repairs Spot positions afterward. | Deduplicate at every level, cache allocation, place directly, manage label collisions and remove post-render repair. |
| CITY-11 / P2 | Three embedded creation panels plus inspector move/binding/relation forms; many dynamic English literals. | Contextual icon actions, shared modal forms, localized errors and progressive disclosure. |
| CITY-12 / P2 | Only Enter/Space node keys; no map navigation stack. `showSpot` can append a late response to a different selection. Deleted current nodes can leave an invalid view. | Directional focus, explicit view state, stale-response guards, valid-parent fallback and separate in-map history. |
CITY-01 describes a confirmed missing check in the inspected call chain, not a
production exploit test. CITY-06 is a code-level scaling/pool risk, not a
measurement of a production DB lock. Additional correctness requirements:
- Path/Revision/policy changes can change map output without changing its
topology-only ETag. Model and authorization generations belong in validators.
- Explicit edges resolve a Page's primary Path, which may be outside the
inferred locality or unreadable. Preserve locality-specific safe portal links.
- Undefined classification currently guesses from name/path substrings. Add an
explicit kind instead of interpreting a user's spelling as system metadata.
- Deleting a generated node requires an exclusion/tombstone; otherwise the next
sweep recreates it. Offer explicit re-enablement.
- Recursive rename already updates City prefixes transactionally. Reuse this
identity-preserving behavior rather than recreating locality UUIDs.
## Component boundaries
1. **URL topology reconciler**: canonical Path bindings → derived memberships
and generated node proposals, running in the existing event scheduler.
2. **Authorized City projection**: topology + metadata → a caller-specific,
bounded navigation model. Geometry never grants access.
3. **Geometry adapter**: stable fabric + permitted model → blocks, connected
Streets, anchors, hit targets and labels. gen-city does not own identity.
Retain gen-city for the first repair and evaluate continuity/capacity/performance
fixtures before replacing it or maintaining a fork. Preserve its license and
rebuild the committed bundle from `assets/city-generator`, not vendor edits.
## URL inference and preservation
- Infer from canonical Domain-scoped Paths, never display slugs, host strings
or repeated URL decoding. Use shared reserved-address rules to exclude user,
group and system routes instead of an incomplete local exclusion list.
- First directory → Quartier; second → Street; third → Spot; deeper descendants
→ that Spot. A directory has descendants and may be virtual (no own Page).
- A locality-boundary Page is its portal, not a child of itself. For example,
`/life/home/kitchen` with descendants is the Kitchen Spot portal;
`/life/home/readme` without descendants is an undefined Page on Home Street.
- A leaf gaining descendants may gain a locality without changing Page UUID.
Change only derived membership, not curated semantic edges.
- `/`, `/life`, `/life/home` remain Domain/Quartier/Street portal Pages. Show
shallow/unassigned Pages at their nearest valid level; do not manufacture
strict-descendant boundaries to force them into a Spot.
- Undefined Pages stay individual yellow-green points. An internal bucket must
not become a fabricated public `/_undefined` portal.
- Store source/rule version and manual overrides separately from descriptions.
Existing nodes and `source=local` edges start as manual/unknown: never adopt
automatically by matching “Generated from URL Paths” text.
- Preview adoption. Reuse exact compatible boundaries; ambiguous ancestors or
descendants need explicit mapping. Keep exclusions, UUIDs and Page content.
- Aliases may infer multiple memberships, but count each Page UUID once in each
aggregate; select readable portal Paths within the locality.
## Event/queue design
Extend the shared transactional outbox; do not install expensive callbacks in
individual HTTP handlers or build a second scheduler. Cover WebUI, CLI, import,
hosted editors, restore, link/unlink, rename and deletion through store writes.
| Committed change | City invalidation |
| --- | --- |
| Path bind/create/unlink/delete; Object deletion | Domain/prefix membership and metadata. |
| Rename/move, including recursive operations | Old and new prefixes; retain locality UUIDs. |
| Revision/edit/restore; filename, MIME or title change | Metadata in Domains binding this Page; unchanged Paths do not regenerate fabric. |
| Topology/manual rules | Affected mapping/layout. |
| Permission/group inheritance change | Authorized projections, not canonical geometry seed. |
| Periodic or manual repair | Same bounded reconciler/checkpoint. |
Proposed persistent state, **not yet migrated**:
- Shared `activity_outbox`: instance/event UUID, Domain sequence, event version,
actor/source, typed Page/Revision target and old/new Path data. Atomic with the
mutation; no document bodies or credentials.
- `city_reconcile_state`: Domain, desired/applied sequence, rule version,
debounce deadline, continuation cursor and last error/job UUID.
- Generated node/membership provenance: stable source key, rule version and
manual override/exclusion; independent of explicit SpotGraph edges.
- Completed model generation: publish finished snapshots, not half-built
reconciliation as a completed map.
Delivery protocol:
1. Commit change and outbox event together; rollback emits no work. SQLite
invalidation triggers may cover legacy writers, but cannot replace actor-aware
events. Unsupported raw SQL edits rely on periodic repair.
2. Consume bounded batches, advance desired sequence and coalesce import/rename
bursts by prefix/Domain. Do not create a full-scan job for every file.
3. Enqueue `city.reconcile`, keyed by Domain. Initial proposed debounce: 2 seconds,
maximum coalescing delay: 10 seconds, configurable to avoid starvation under
continuous editing. These are starting values, not measured tuning results.
4. Capture watermark N and process bounded batches (initial target: 200 Paths,
short transactions). Persist derived changes and progress together. Reconcile
current state; do not replay stale rename payloads as commands. Recheck source
generation before publishing a completed snapshot.
5. Acknowledge only processed N. If desired advanced while queued/running, enqueue
a successor **after the active job finishes**, or let the dispatcher do so.
Current active-key queue deduplication must not acknowledge/drop newer edits.
6. Retries are idempotent; unchanged data does not increment topology version.
Keep itemized conflicts/cursors. Queue-full, pause, crash and cancellation
preserve pending invalidations and unprocessed events.
7. `city.reconcile.sweep` is a fair, bounded recovery pass across Domains using
the same algorithm. Compact outbox only after consumers' checkpoints/retention
requirements allow it.
Use existing `/_/api/v1/event/` and `/_/api/v1/queue` definitions, trigger, job and
log mechanisms. Proposed City event types are **not registered yet**. When POST
`/city/autoplan` becomes asynchronous, return `202` with a job UUID and update
its UI simultaneously. Dry-run needs bounded results and a base/rule-version
token; stale approval must not silently apply a newly recomputed plan.
Settings are Domain-scoped. Existing Domains start manual; enable URL-auto after
an adoption preview. New-Domain URL-auto defaults can follow once gates pass.
Manual/scheduled triggers share settings and permission checks. Workers may
mutate derived City state only, not arbitrary Pages using an administrator token.
Use low priority, one City writer per Domain, shared preview/import resource
budgets, cancellation and backoff. Keep geometry out of write transactions and
request handling. This is single-writer operation: current startup requeue of
all running jobs is not an HA lease; multi-instance workers require fencing.
## Geometry and read scalability
- Fabric key = Domain UUID + explicit seed + generator/version/options. Ordinary
edits and topology increments must not change the seed.
- Layout key = fabric + structural/membership generation + layout version;
metadata/policy generations are separate. Preserve prior assignments with
bounded growth/shrink hysteresis to avoid global rearrangement for one Page.
- Build a connected road graph, clip at Quartier boundaries, allocate fairly,
project anchors onto bounded segments. Keep every locality pickable with
explicit fallback/capacity warnings when geometry is scarce.
- Deduplicate weights at every level; leave unoccupied space when membership
is small. Use zoom-dependent labels/aggregation for dense points.
- Worker generates/allocates with size/time/cancellation limits; viewport/zoom
bounds main-thread rendering separately. Superseded results cannot replace
newer views. Remove observer-driven placement repair after regression tests.
- Top-level API returns Quartier summaries, not every descendant Page. Lazy
bounded Street/Spot/Page APIs use bulk queries, snapshots and cancellation.
- Cache authorized models by Domain, principal/policy and data generation with
private HTTP validators. Invalidate on logout/policy change; don't put restricted
labels/coordinates in a shared origin-wide cache. Topology-independent fabric
can be cached separately. Remove unused `city-geometry.js` storage work.
- During regeneration keep the last valid authorized map, with a small status
icon. Failures provide a directory fallback/retry, never block Page navigation.
## Compact UI and keyboard contract
- Toolbar: breadcrumbs, search, zoom/reset, add icon, settings icon. Generation
status tooltip links to details and existing job monitor, not verbose inline text.
- Add opens one modal for Quartier/Street/Spot with contextual parent/Path defaults
and ancestry/conflict validation. Page bindings/relations use the same modal
shell. Preserve inputs on failure, prevent duplicate submits and scope parents.
- Settings modal: manual/URL-auto, adoption preview, rules/exclusions, event timing
and explicit regeneration. Changing fabric seed is a separate confirmed action.
- Accessible icon names/tooltips, adequate hit areas, visible focus, Japanese and
English strings, trapped/restored modal focus. Escape closes innermost overlay
before outer map popup. No global form-input shortcuts.
| Key, only while map navigation is focused | Action |
| --- | --- |
| Arrows; W/A/S/D; K/H/J/L | Focus nearest visible selectable node up/left/down/right, without activation. |
| Enter / Space | Open locality or activate Spot portal/Page, matching click behavior. |
| Backspace | Parent City level, without leaving the page. |
| `+` / `-`; `0` | Zoom in/out; reset viewport. |
| Shift+F10 / Context Menu | Context menu on focused node. |
| Escape | Close menu/modal/map popup from inside outward. |
| Tab / Shift+Tab | Native accessible traversal, roving tab stop within map nodes. |
Do not intercept input/textarea/select/contenteditable, IME or Ctrl/Alt/Meta
shortcuts. Pointer drag pans; directional keys navigate nodes, with defined
offscreen/empty-view fallback. Refresh preserves selection/zoom; deletion falls
back to nearest valid parent. Guard async inspector/load responses by selection
and request generation, and cancel obsolete requests.
Locality history is an in-memory stack, not a browser entry for each movement.
Existing back/forward buttons invoke browser history; they cannot provide
per-locality traversal without entries. Provide distinct map back/forward
controls instead of pretending these two requirements are equivalent.
## Delivery and acceptance checklist
1. [ ] **CITY-A — correctness gate**: denied descendants, literal Paths, scoped
names/links, shallow/portal rules, source-aware idempotent plan/apply.
2. [ ] **CITY-B — durable events**: outbox and watermarks, consumer, CLI/import/
adapter coverage, concurrent-edit/rollback/retry tests, manual/scheduled/auto UI.
3. [ ] **CITY-C — responsive map**: stable seed/cache, Worker, connected allocation,
capacity fallbacks, lazy authorized reads and continuity/stale-result tests.
4. [ ] **CITY-D — compact navigation**: icons/modals, keyboard/i18n/focus/history,
popup and error recovery browser tests.
CITY-C/D may proceed independently of CITY-B once CITY-A's read/identity
contracts are established. Do not enable automatic production reconciliation
before CITY-A/B pass. Main-roadmap P0 authentication work remains open.
Fixtures: 500 / 5,000 / 50,000 Paths, aliases, many tiny Streets, one crowded
Street, virtual folders, repeated names, `%`/`_`/Unicode, manual/archived mappings,
denied descendants, rename/edit during generation, crash/queue-full/retry/cancel.
Record API p50/p95, response size, query count, SQLite write-lock duration,
generation CPU/memory and browser long tasks before fixing production budgets.
Audit checks performed locally:
- Passed existing tests: `GOCACHE=/tmp/pageswiki-go-cache go test
./internal/store ./internal/server -run 'TestCity|Test.*City|Test.*Topology'
-count=1`. These do not cover all findings above.
- Ran the checked-in gen-city bundle in a Node VM three times, seed key
`audit-city:1`, dimensions 240×160. Synchronous call times: about 39/32/29 ms;
259 roads and 279 buildings each. A zero-delay timer did not run before
generation completed. This supports the source finding of synchronous work,
not a browser/production latency benchmark.
- No live DB mutation, schema migration, runtime/UI change or deployment in
this audit.
+76
View File
@@ -0,0 +1,76 @@
# City generation Worker and directional navigation
Implemented bounded CITY-C/D slice, 2026-09-14. Preserves the generated fabric
and [courtyard projection](city-immersive-map.md); this does not replace the
server topology/reconciliation work in [the City audit](city-review-and-reconciliation.md).
## Generation and lifecycle
`city-generator-client.js` retains the asynchronous `PagesWikiGenCity` facade,
but the generator bundle is no longer loaded into the main document. A local
`city-generator-worker.js` imports the rebuilt gen-city 1.4.6 bundle and returns
only numeric roads/building polygons. Its synchronous internals therefore cannot
block browser input or navigation. The Worker is terminated when finished, on
abort/supersession, on page suspension, or after a 5-second deadline. There is
one active generation job per map/client. Same-key requests share the job.
Inputs are limited to a 256-character stable Domain key and integer dimensions
64–320 by 64–240 (the map requests 240 by 160). The adapter and Worker enforce
these bounds; returned geometry is limited to 4,096 roads, 4,096 buildings and
16 finite vertices per building. The main-thread deadline can kill runaway
synchronous Worker code without waiting for it to process a cancellation message.
The base seed is the Domain UUID, not a topology version or membership count.
Geometry-only caches use the generator/layout version, Domain UUID and dimensions
as their key. Memory and sessionStorage each retain at most three fabrics; a
serialized storage entry must fit 512 KiB. Storage denial, quota exhaustion and
corruption do not disable generation. No Page names, Paths, grants, topology
or principal information are cached here. Authorized API results remain separate.
The map aborts superseded fetches and discards late render responses. `pagehide`
cancels fetch/generation; BFCache `pageshow` reloads the authorized model and
reuses valid geometry. An unsupported/blocked Worker, timeout or malformed result
shows a retry action and error without executing gen-city synchronously as a
fallback. Utility menus remain usable; this is not a claim that the map works
without Workers. The SVG exposes its busy state to assistive technology.
## Keyboard interaction
`city-navigation.js` handles directional focus over currently visible Quartier,
Street, Spot entry, Page/portal links and overflow controls:
- Arrow keys, WASD and HJKL choose the nearest useful candidate in the requested
screen-space direction; there is no arbitrary wrap across the map.
- Enter/Space activates the focused element. Repeated activation keydown is
suppressed to avoid drilling through multiple levels while a key is held.
- Backspace moves to the parent locality and restores the former child's focus.
At the Domain level it stays in the map. It never calls browser back/history.
- Ctrl/Command/Alt shortcuts, IME composition, editable fields, controls outside
the map, open modals and context menus are not consumed. Ctrl selection and
existing dialogs continue to work. Escape remains available to the containing
popup/menu rather than being repurposed for hierarchy navigation.
The existing mouse, semantic Page hrefs, popup top-window Page navigation,
horizontal labels and courtyard design are unchanged. Navigation changes local
view state only; actual Page links still navigate normally.
## Verification and remaining limits
Opt-in Chromium tests run in normal and popup modes with the real Worker and
real gen-city output. They cover stable repeated seeds, a deliberately busy
Worker while main-thread timers keep running, timeout/abort/supersession,
stale messages, storage bounds, invalid results and pagehide/BFCache resumption.
Keyboard tests cover all key families, semantic Page activation, focus restoration,
modifier/IME/editing/modal exclusion and unchanged URL/history. Existing label,
organization, immersive/pagination and mobile-light-theme fixtures still pass:
```sh
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestCity(Labels|Organizer|Immersive|Keyboard|Worker)Chromium' -count=1
```
This isolates base-fabric generation, not all City work. Topology-to-road
allocation, SVG DOM construction and loaded directory/inspector options remain
on the main thread. Connected road allocation, lazy locality projections and
larger-scale DOM virtualization remain separate tasks. A future server-side
geometry cache could share work across tabs/devices; no cross-tab worker pool
or server generation scheduler is introduced here.
+194
View File
@@ -0,0 +1,194 @@
# Configuration panels, bookmarks, and resource charts
Resource history is now collected by a built-in background event, not by an
open browser. The current persistence, retention and extension-catalog design
is specified in [System extensions](system-extensions.md); it supersedes the
earlier in-memory live-sampling description below.
Bookmark sections and direct home-page management are specified in
[Home navigation and hosted Vim](home-bookmark-sections-vim.md). The flat
bookmark representation below remains compatible; section rows extend it.
## 設定画面の構成
`/-/sys/config?panel=<id>` を共通シェルとする。`config_panels.go` の
サーバー所有レジストリがグループとパネルIDを定義する。
| グループ | パネルID |
| --- | --- |
| 表示・ナビゲーション | `home`, `editor`, `bookmarks`, `nav-home`, `nav-system` |
| コンテンツ | `objects`, `assets` |
| 認証・アクセス | `auth`(アカウント), `auth-providers`, `auth-sessions` |
| キャンパス・ドメイン | `campuses`, `domains` |
| 連携アダプタ | `adapters`, `adapters-builtin`, `adapter-<plugin-id>` |
| 運用 | `scheduler`(実行状態・リソース), `logs`(実行履歴・ログ), `events`, `queue` |
選択グループを展開し、他グループは折りたたむ。各summaryは手動でも開閉可能。
サイドバー全体を閉じた場合は本文の幅も広げる。小画面は縦並びとする。
パネル選択をURLに反映するため再読み込み/直接リンクで同じパネルを開ける。
既存の `panel=nav` は `nav-home` として扱う。
共通CSSは `/static/css/config.css`、遷移・APIエラー処理・グラフは
`/static/js/config-panels.js`。チェックボックスはネイティブinputを残した
`role=switch` とし、labelの `data-label` をCSSの `attr(data-label)` で表示する。
inputにも翻訳済み `aria-label` を付け、キーボード操作・disabled・フォーム所属・
送信値を保持する。秘密情報は既存のpassword入力と空欄時保持の契約に従う。
## スケジューラの情報分離
- 実行状態: 件数、直近25ジョブ、再試行/キャンセル、プレビュー生成の手動トリガー。
- イベント: 実施タイミング、次回実行、追加/実行/削除。周期と日時は選択した
スケジュール方式に対応する項目だけ表示。優先度・試行回数・JSONは詳細設定に置く。
- キュー: 一時停止、並列数、キュー深度、リトライ待ち時間、履歴保持。
- ログ: 直近50件の実行ログ。
- リソース: 下記のライブグラフ。
従来はスケジューラを開くと4種類のAPIをまとめて取得していた。現在は選択した
パネルで必要なAPIだけ取得し、遷移時に中止する。定期取得はリソースパネルに限定。
設定フォームを定期更新で上書きしない。APIの非JSONエラーも本文/ステータスとして
表示し、JSON構文エラーで本来のエラーを隠さない。
## アセット一覧の障害と是正
報告: `Unexpected token 'o', "forbidden: "... is not valid JSON`。
原因はGETがendpoint policyに登録されていなかったこと。POST/DELETEの登録により
同じエンドポイントがmethod-closedになり、一覧GETが認可ハンドラに到達する前に
拒否されていた。GET/POST/DELETEは型付きpolicyからアセット管理ハンドラへ渡し、
現行のキャンパス/ドメイン管理者権限をハンドラで検証する。
調査時の `asset:image:profile` は、HEAD、履歴、実ファイルSHA-256が一致し、
記録サイズ・実サイズともに2,627バイトだった。データを削除・再生成する必要はない。
あわせて以下を是正した。
- 参照数を「同一ドメインにPathを持つ参照元Revisionの異なり数」に統一。
過去HEADと現在HEADを含める。詳細はPath別の行を返すため、同じRevisionの
別名Pathがある場合の行数は参照数と一致するとは限らない。
- HEAD履歴がない旧データも、現在HEADから依存関係を取得可能にした。
- 更新/削除は書き込みSQLでも期待HEADを比較し、競合を検出する。
- 同じバイト列でもMIME/ファイル名を変えた場合はメタデータと履歴を更新する。
- CLIのアセット書き込みもMIME、ファイル名、サイズ、履歴を同一トランザクションで更新。
- 一覧APIは `no-store`。画面はテキスト形式の拒否応答も読み取れる。
HEADハッシュのETagはバイト列の識別子である。メタデータだけの同時更新を厳密に
区別するには将来、Asset状態バージョンを含めた条件付き更新契約が必要。
## ブックマークマネージャー
`panel=bookmarks` でドメイン共通のブックマークを最大64件管理する。
行には名前、指定方法(Path / URL)、宛先、上下移動、削除を用意する。
保存時に管理者権限を検証し、入力が不正なら保存済み一覧を変更しない。
既存の `home_bookmarks` JSONを継承し、`kind` を任意追加する。
```json
[{"label":"Docs","kind":"path","href":"/docs"},
{"label":"External","kind":"url","href":"https://example.com/"}]
```
Pathはドメインルート相対の意味を持ち、URL化するときに空白・%・Unicodeを
適切にエスケープする。URLはHTTP(S)またはルート相対URLを許可し、JavaScript、
プロトコル相対URL、資格情報を含むURLは拒否する。ローカルの宛先は表示時にも認可する。
ホーム設定の保存ではブックマークを更新せず、別パネルの保存で消える事故を防ぐ。
現在は「検索+ブックマーク」のホームに反映し、共通サイドバー実装時に同じデータを使う。
個人ブックマーク、フォルダ分類、UUID追従型ブックマークは将来の別拡張とする。
## 設定テーブルの表示密度
設定画面の `.recent-table` / `.config-form-table` に限定して行の余白を圧縮する。
セルの上下paddingは0.22rem、行内コントロールは高さ1.8rem、セル内フォームの外余白は0。
空のform要素は表示しないが、form IDを用いた行内入力・保存/削除との関連付けは維持する。
名前と識別子を1行にまとめ、通常セルは折り返さず、幅不足はテーブル領域内で横スクロール。
長いPath・ファイル名・URL・補足説明は全文をDOMとtitleに残した省略表示とする。
ログ展開行とその本文は例外として複数行表示を保つ。Viewer/Editorなど他画面のテーブルには適用しない。
## リソースグラフ
`scheduler` パネルはhtop型の監視画面とし、上部に現在値と4つのグラフ、下部に
実行中ジョブのみを表示する。旧 `panel=resources` は `scheduler` の別名として維持。
収集設定・表示期間・自動更新・指標の説明は、タイトル横の歯車から開くネイティブdialogに
まとめる。閉じるボタン・Escape・背景クリックで閉じ、歯車へフォーカスを戻す。
別パネルへの移動時も閉じる。表示設定は即時反映し、同一originのlocalStorage
`pageswiki.monitor.display.v1` に期間・自動更新ON/OFF・現在値とグラフの更新間隔を保存。
初期値は1時間・自動更新ON・現在値1秒・グラフ5秒。保存された期間があれば優先する。
不正な値は使わず、storage利用不可でも既定値で動作する。収集設定は保存操作でDBへ永続化。
時間範囲はタイトル直下に1つだけ表示し、各グラフの時間ラベル・表示点数は出さない。
更新操作はリロードアイコン、設定は歯車。履歴へのリンクはサイドバーに集約する。
グラフは常に1行4列。狭い画面ではグラフ領域内だけ横スクロールし、2列/1列へ折り返さない。
`GET /_/api/v1/queue/resources` の現在値と `GET /_/api/v1/queue/jobs?status=running&limit=100`
を既定1秒間隔で取得する(要求完了後に次を予約し、重複実行しない)。実行中の絞り込みはLIMITより前にDBで行い、最近終了した
ジョブに長時間実行ジョブが埋もれない。ワーカー上限32に対し表示上限100。
現在値のキュー統計はstatus索引で待機・実行中だけを集計し、完了履歴を全走査しない。
グラフは既定5秒ごとに、現在値から得たライブサンプルを履歴へ重ねて描画する。
両間隔は1〜60秒で設定可能。グラフ間隔は現在値の間隔以上に補正する。
永続履歴APIの再取得は30秒ごとに抑え、期間変更と手動更新時は即時再取得。
ライブバッファも描画も最大361点。I/O速度は間引き前に計算し、時間バケットの最終値を描く。
ブラウザ内ライブサンプルはDBへ書き戻さず、再起動後は永続サンプルから復元する。
バックグラウンド収集は引き続きビルトイン
`resource.sample` イベントで行い、画面を閉じても7日間保持する。
詳しい収集契約は [システム拡張](system-extensions.md) を参照。
パネルを離れる、タブが非表示になる、自動更新を止める場合は定期取得を停止する。
取得中リクエストはAbortControllerで中止し、古い結果が再表示しないよう世代を管理する。
グラフはテーマの色を使ったSVGで、外部ライブラリ/CDN不要。
### 実行履歴とログ
`logs` パネルにジョブと実行ログを統合。既定は終了状態
(succeeded/skipped/failed/cancelled)、待機・個別状態のフィルタも用意する。
`GET /_/api/v1/queue/jobs?status=history&limit=50&cursor=...` のkeysetページングで
50件ずつ置換し、DOMへ無制限に追記しない。順序は投入時刻降順+UUID降順。
完了状態用partial indexを指定し、SQLiteが状態別索引のIN検索後に保持履歴全体を
一時ソートする計画を避ける。ジョブpayloadは一覧SQLでも応答でも読み出さない。
新しいジョブへは更新ボタンで戻る。cursorは位置を表すのみで認可は毎要求再検査する。
ログはジョブの展開時だけ `/_/api/v1/event/logs?job_uuid=...&limit=100` で取得。
以前のログは `before_id` で100件ずつ置換する。内容はHTMLではなくテキストとして表示。
実行中のキャンセル、失敗等の再試行を維持する。終了した実行中行は次回更新で消える。
実行状態は秒数・試行数を示すが、ジョブ別のCPU/RSS計測や進捗率を捏造しない。
| 指標 | 意味 |
| --- | --- |
| CPU | ホストの1分ロードアベレージ。CPU使用率ではない |
| メモリ | このGoプロセスのheap bytes |
| I/O | PagesWikiプロセスの読み込み・書き込み速度(B/s)。2系列で表示 |
| キュー負荷 | 待機ジョブ数+実行ワーカー数 |
これらはドメイン別ではなくインスタンス/ホスト単位の指標。
ディスク容量は現在値カードに残し、グラフの1枠はI/Oに使う。I/Oの計測範囲と制約は
[システム拡張の監視仕様](system-extensions.md#ディスクio)を参照。
コンテナCPU制限・RSS・cgroup使用率・複数インスタンス・長期保管は将来の
監視プロバイダ拡張として別API/保持方針を設計する。
## アダプタ個別パネルの拡張契約
現行プラグインは `adapter-<id>` に個別パネルを持ち、共通partialで接続先・
対応MIME/拡張子、有効化、別タブ、既定エディタ、HTML/Markdown変換を編集できる。
旧 `/-/sys/config/adapters?id=...` のGETは統合パネルへリダイレクトする。
保存も同じパネルに戻り、ドメイン別の既存プラグイン設定へ保存する。
将来のアダプタ固有項目は次の契約で追加する。
1. サーバーが信頼するmanifestに `settings_schema_version` と複数のパネル定義を登録。
定義は `id`, `title_key`, `group`, `fields` とし、フィールドはboolean、text、
enum、number、secretの許可リストから選ぶ。現行partialがその最初の実装。
2. 保存先は `(domain_uuid, adapter_id, schema_version)` で区切る。バリデーションと
schema移行はサーバー所有。未定義キーは拒否し、秘密値は読み出しレスポンスに含めない。
3. 特殊UIが必要な場合のみ、サーバー登録済みの専用partial/モジュールを使う。
プラグインやドキュメントから任意HTML/JavaScriptを設定画面に挿入しない。
4. 外部設定画面の埋め込みが必要な場合は、別途sandbox iframeと固定originの
postMessage契約を設計する。通常ログインCookie/Bearerをiframeへ渡さない。
5. アダプタ固有の接続確認・秘密管理・長い検証処理は個別APIとイベントへ分離。
汎用schema rendererと外部設定iframeは未実装。今回の共通シェル・レジストリ・
アダプタpartialを拡張点として使用する。
## 検証
- 管理者のAsset GETが成功し、一般ユーザーのGETが拒否されるHTTP回帰テスト。
- 参照数のドメイン分離、旧HEAD参照、同一バイト列のメタデータ訂正。
- ブックマーク保存/不正URL拒否、アダプタ個別設定の保存と戻り先。
- 設定HTMLの重複ID、メニューの未定義パネル、inline JavaScriptの構文検証。
- Chromiumでassets/events/queue/resources/bookmarks/adapter個別パネルを確認。
`PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run TestConfigChromiumSmoke`
- CLI: `python3 -m unittest discover -s data -p test_cli_assets.py`。
+183
View File
@@ -0,0 +1,183 @@
# Data CLI
`data/pageswiki-cli` is a local administrative data surface. It provides
rsync-like one-shot transfers and an interactive Semantic Path shell.
It accesses:
- metadata in `pages.db`;
- immutable payloads in `documents/sha256/`;
- mutable Asset HEAD metadata in `assets`.
The implementation uses Python's standard library only.
## Invocation modes
### One-shot
```bash
data/pageswiki-cli get path:/manual/start start.html
data/pageswiki-cli put start.html path:/manual/start
```
Transfers compare SHA-256 before writing. Identical content is reported as
`skipped` and does not create another Revision.
### Interactive shell
```bash
data/pageswiki-cli shell
```
Invoking without arguments also opens the shell when stdin is a terminal.
The shell maintains a Semantic Path working directory:
```text
pages:/> cd /manual
pages:/manual> ls
pages:/manual> view start
```
The shell uses `readline` when available:
- Up/Down traverse command history.
- Tab completes commands, Semantic Paths, UUIDs, Revisions, Assets, and local
transfer paths.
- History persists in `~/.pageswiki_history`, or the path specified by
`PAGESWIKI_HISTORY`.
## Commands
| Command | Behavior |
| --- | --- |
| `ls [PATH]` | List direct Semantic Path children |
| `cd PATH` | Change shell Semantic Path |
| `mv SOURCE DEST` | Move a Path and its descendants transactionally |
| `view [ADDRESS]` | Display metadata and send payload to `PAGER` on a TTY |
| `cat [ADDRESS]` | Write only the canonical payload to stdout |
| `edit [ADDRESS]` | Edit through `EDITOR` and write back changed content |
| `get ADDRESS [LOCAL]` | Download one payload |
| `put LOCAL ADDRESS` | Upload a Page Revision or update an Asset HEAD |
| `mget REMOTE_PATTERN [DIR]` | Download matching Semantic Paths |
| `mput LOCAL_GLOB REMOTE_DIR` | Upload matching local files |
| `revision [ADDRESS]` | List a Page's immutable Revision history |
| `diff REV REV` | Produce a unified Document diff |
| `restore REV` | Create a new Revision from an old Revision |
| `link ADDRESS PATH` | Add a Semantic Path projection |
| `unlink PATH [ADDRESS]` | Remove a Path projection only |
| `pwd` | Show the shell Semantic Path |
`put` and `mput` infer a Revision Content-Type from the local filename, with
the destination Semantic Path as a fallback. Markdown input is converted to
canonical HTML and loses only its `.md` / `.markdown` Semantic Path suffix.
Other extensions remain part of the Path. Binary payloads are stored as
immutable Documents and retain their original filename and Content-Type.
| `help` | Show usage |
| `exit`, `quit` | Leave the shell |
`get ADDRESS -` writes to stdout and `put - ADDRESS` reads from stdin.
Unlike `view`, `cat` never invokes a pager and is suitable for pipelines.
## Supported addresses
| Address | Meaning |
| --- | --- |
| `path:/...` | Mutable Semantic Path projection |
| `uuid:<uuid>` | Stable Page/Object identity |
| `rev:<uuid>` | Immutable Revision identity |
| `asset:<type>:<name>` | Mutable Asset HEAD |
A single address without a command retains the earlier inspection behavior.
## Write semantics
### Page `put`
1. Resolve `path:` or `uuid:`.
2. Create a Page UUID and Path binding if a Path does not exist.
3. Hash the input and atomically persist its immutable Document.
4. Compare with the newest Revision in `PAGESWIKI_LANG`.
5. Skip identical content or create a new Revision UUID.
Page payloads must be UTF-8. Binary data belongs in an `asset:` address.
### Asset `put`
1. Hash and atomically persist arbitrary bytes.
2. Create the Asset identity if absent.
3. Skip an identical HEAD or update `head_document_hash`.
### `edit`
1. Resolve the current canonical payload.
2. Write it to a private temporary file.
3. Invoke the command in `EDITOR`.
4. Apply Page or Asset `put` semantics when the editor exits successfully.
5. Skip unchanged content and remove the temporary file.
Immutable `rev:` addresses cannot be edited.
### `mv`
- Semantic root cannot be moved.
- A destination cannot be inside its source.
- Every destination is collision-checked before mutation.
- A unique temporary namespace avoids primary-key collisions.
- All Path updates commit in one SQLite transaction.
### `restore`
Restore never rewrites history. It reads the selected immutable Revision and
creates a new Revision on the same Page with the same language.
### `link` and `unlink`
These commands mutate reachability only. They never delete the Page,
Revisions, or Documents. An unlinked Page may become a zombie and remains
recoverable by UUID until garbage collection.
## Consistency and safety
- SQLite writes use explicit transactions and a busy timeout.
- The CLI initializes the additive `assets` table when absent; core schema
migrations remain owned by the server.
- Documents use temporary files, `fsync`, and atomic replacement.
- Payload hashes are verified on every read.
- Revision addresses reject writes.
- rsync-like transfers skip identical hashes.
- Missing canonical Documents may use the transitional SQLite body only when
its SHA-256 matches.
This CLI is a trusted local administrative interface and intentionally bypasses
future HTTP Capability evaluation. Filesystem and database permissions define
who may use it.
## Environment
| Variable | Meaning |
| --- | --- |
| `PAGESWIKI_DATA_DIR` | Directory containing `pages.db` and `documents/` |
| `PAGESWIKI_DB` | Explicit SQLite path |
| `PAGESWIKI_DOCUMENTS_DIR` | Explicit Document root |
| `PAGESWIKI_LANG` | Language used for selection and Page writes |
| `PAGER` | Pager invoked by `view` on an interactive terminal |
| `EDITOR` | Editor invoked by `edit` |
| `PAGESWIKI_HISTORY` | Interactive command-history file |
## Asset metadata
The normative Asset lifecycle and authorization model are defined in
[`asset-model.md`](asset-model.md). The CLI is a trusted local implementation
of HEAD reads and updates, not the public Asset API.
| Column | Meaning |
| --- | --- |
| `domain_uuid` | Domain containing the mutable Asset name |
| `address` | Canonical Domain-local `asset:` address |
| `object_uuid` | Stable owning Object UUID |
| `head_document_hash` | Current immutable Document snapshot |
| `created_at_ms` | Creation timestamp |
| `updated_at_ms` | HEAD update timestamp |
Administrator HTTP Asset mutation is available with Domain/Campus-admin checks
and ETag preconditions. The CLI remains the trusted local bulk interface.
+278
View File
@@ -0,0 +1,278 @@
# 日記・ブログ:ビルトインシステム拡張
初期版 0.1/URL・入口拡張(2026-09-17)。MIME連携アダプタではなく、通常のWiki Pageに
付随する日付・記事情報とナビゲーションを提供する。任意の外部コードをロードする
プラグイン機構ではない。
## 実装した範囲
| | 日記 | ブログ |
| --- | --- | --- |
| ID | `content.diary` | `content.blog` |
| UI | `/v/diary` | `/v/blog` |
| 設定 | `/-/sys/config?panel=diary` | `/-/sys/config?panel=blog` |
| 一覧 | 月別/日付別 | 日付降順、任意の月・カテゴリで絞り込み |
| ナビゲーション | 月カレンダー、最近8件、自分の記事 | 月カレンダー、最近8件、カテゴリ、自分の記事 |
| 登録制約 | 同日複数件可 | 同日複数件可 |
両方ともDomainごとに**既定無効**。Domain管理者が有効化する。無効化しても
登録情報、Wikiページ、Revisionは削除しない。
「新規記事」ダイアログは日付・keyword・タイトル・カテゴリ・Markdown本文を
まとめて保存する。既存Pageを使う場合は従来のPath指定による登録も可能。
本文の継続編集は既存エディタ、記事情報の変更・登録解除は一覧から行う。
## 同一インスタンスのDomain射影(第一段階)
- ドメイン一覧の歯車内で日記・ブログそれぞれの参照元DomainとPath prefixを指定。
空の参照元は従来の自Domain記事を表示する。入口形式・有効状態は上の設定で指定する。
- `periodical_projections(domain_uuid,kind,source_uuid,prefix)`で参照のみ保持し、
Page、Revision、Path、記事情報は複製しない。既存の表示先記事も削除しない。
- Campus管理者による設定に限定。同じCampus(同じコントローラの管理単位)の
有効なlocal配置Domain同士のみ許可。managed Campus上のローカル設定変更は禁止。
自己参照・連鎖・循環を拒否し、閲覧時にも有効状態・配置・所属・連鎖を再検査する。
- 初期射影範囲は認証済みの一覧・月/日カレンダー・カテゴリ・最近の記事・own。
参照元・表示先の双方の読取ポリシーとprefixで絞り、件数/カテゴリ/ページ送りを
その後に計算する。ソース権限は一括読込し、記事ごとのSQL認可問い合わせはしない。
Source側がlegacyモードでも、射影では明示的な読取権限を要求する。
- 匿名の場合も、設定済みのlocal射影先の `/` と `/v/{kind}/YYYY/MM[/DD]` を
閲覧できる。参照元の現在有効な公開承認済みPath/Revisionだけから一覧・件数・
最近の記事を構成する。日付は承認済み `{prefix}/YYYY/MM/DD[/keyword]` Path、
**登録タイトルはPageの公開状態を継承する公開表示情報**とする(2026-09-19変更)。
現在有効な公開承認のあるPageのタイトルだけをJOINで取得し、タイトル変更は
次の要求で反映する。カテゴリ・著者・登録日付は公開しない。タイトル未登録なら
最新20記事に限り承認済みHTMLのh1を64KiB以内で読み、なければ日付/Path末尾。
不正/期限切れの認証情報は匿名へ降格しない。公開変更/失効は次の要求で反映する。
記事本文の公開権限を増やさず、未承認の最新Revisionを公開しない。
- 表示先の認証セッションでPrincipalを特定する。参照元の同じPrincipalに読取権限が
必要。クロスサブドメインCookie共有やセッションの暗黙継承は実装しない。
- 専用ドメイン(入口形式がblog/diary)では記事リンクを表示先の
`/YYYY/MM/DD[/keyword]` とし、承認済み本文を同じホストで表示する。
カレンダー・同月の他の記事(最大31件)・前後の記事を同じ公開集合から構成する。
サイト名称・テーマは表示先Domainのもの。記事本文は既存のinert HTML境界を使う。
本文中の既知の公開記事リンクも表示先へ変換し、それ以外は参照元URLを保持する。
画像のCSPは設定済み参照元originだけ追加許可し、画像自体の公開権限は拡張しない。
「参照元で閲覧・編集」は従来通り元FQDNへ移動する。作成・登録・更新・解除の
APIを射影先で使うと403。Store transaction側でも射影設定を再検査して拒否する。
- entries APIは`source_domain`・`source_origin`・`projection`を付加する。
Path/Page UUIDは参照元のもの。日付ナビゲーションは表示先の `/v/{kind}/...`。
日付既定値は参照元Timezone、テーマ・名称は表示先Domainの設定。
- 一覧は毎回DBから読み、`private, no-store`。ACL失効・元記事変更は次の要求で反映。
参照先が無効/remote配置/別Campusへ変わった場合は503で閉じ、自Domain記事への
黙った切り替えはしない。同期や既存公開承認をこの参照設定で拡張しない。
- この参照設定は現時点では**ローカル専用でmanifest v2には含めない**。
別インスタンスへの参照設定配信・認証付き取得・失効・
タイトル以外の匿名メタデータ公開・SSOは後続。従って「同じコントローラなら任意の配置先で射影」
までを実装済みとはしない。
- 専用ドメインの `/rss.xml` はRSS 2.0、最新20記事のタイトル・正規リンク・GUID・
Revision日時と、`content:encoded` の安全化済み本文HTML(CDATA)を配信する。
本文取得前に正確なRevision公開承認を再確認する。記事リンク・ページ内リンクは
表示先の絶対URL、画像やその他の参照元リンクは元ドメインの絶対URLに変換する。
上限は1記事1MiB入力、本文合計8MiB、生成処理5秒。上限超過は503とし、黙って
本文を切り捨てない。HEADは本文を生成しない。非公開登録情報は含めない。絶対URLは登録FQDNから
作り、Hostヘッダー由来のfeed汚染を防ぐ。HTMLにRSS autodiscoveryとRSSリンクを設置。
毎回公開承認を確認し、HTTP共有キャッシュは使わない。ただし購読者が既に取得した
RSSや本文のコピーは、公開撤回しても遠隔削除できない。
## 原子的な新規投稿のAPI
- `/v/blog/-/new`、`/v/diary/-/new` は認証必須の独立した新規記事画面。
Domain timezoneの日付・keyword・カテゴリ・Markdown本文を既存posts APIへ送る。
作成/Pathの権限はAPI内のtransactionで検証し、保存だけでは公開承認しない。
未有効のプラグインは404、射影先は参照元の同ルートへ303で案内する。
GETで記事やPathを作成せず、POSTはこの画面URLでは受けない。
- 投稿完了画面にXのWeb Intentリンクを表示し、ユーザのクリックでのみXへ移動する。
サーバーからの自動投稿・外部SDK・OAuth資格情報の保持は行わない。
posts応答の`share_targets`は有効な同Campus/local射影先と入口設定から生成する。
ブログ専用ドメインの `/YYYY/MM/DD[/keyword]` を優先し、複数なら選択式。
射影設定があるのに利用可能な共有先がなければ、元ドメインへ黙って切り替えない。
`published`は公開承認の検査結果。未公開なら警告とクリック時の確認を出す。
共有操作で公開承認は変更しない。公開記事ページにはタイトル・canonical URLの
OGP/Xカードメタデータを出す(カードの表示や更新時期は外部サービス側に依存)。
- `POST /_/api/v1/extension/content.{diary|blog}/posts`:`request_id`(UUID)、
`title`、`date`、`keyword`、`category`、`body`(Markdown)。未知フィールド拒否。
要求JSON上限320 KiB、変換後HTML上限256 KiB。ブラウザ本文入力上限131072文字。
- prefixとTimezoneはサーバー設定を使用する。Path・Page UUID・著者の指定は不可。
通常のMarkdownレンダラでHTML化し、通常のRevision挿入関数とasset固定処理を共有。
- SQLite write予約後にactive membership、ローカル配置、有効状態、create/writeの
両権限、上位Locality制限、現在のprefix、Pathの不存在を検査する。
Page・provenance・Path・Revision・asset参照・記事情報・journal・再送receiptを
同一transactionで確定する。既存Pathは409で拒否し、上書きしない。
- `periodical_posts`のDomain/kind/actor/request_idと要求digestで再送を識別する。
同じ要求は既存Page UUIDを返し、変更された要求は409。再送にも現在の権限と
Path binding/記事登録の存続を要求し、削除後の再送で復元しない。
- Document Storeのimmutable blobはcommit前に書き込む。DB rollback時には
未参照blobが残り得るが、Page・Revision・Path・記事索引は可視化されない。
未参照blob回収とreceipt保持/GCの統合は後続。プロセス内revision書込ロックを共有。
- 本文保存は公開承認ではない。匿名の本文・記事情報・日付・件数を追加公開しない。
- 日付付き一覧へ遷移して保存結果を表示する。ダイアログ内の入力は送信失敗時に
保持し、同じrequest_idで再試行する。ブラウザ永続ストレージには下書きを保存しない。
- Search/公開失効など既存DB triggerは共通Revision/Path挿入で適用される。
City自動生成・通知への共通outbox配送は依然として後続(journalだけで配送済みとしない)。
## 記事URLとドメイン入口(2026-09-17)
- 設定画面の日記/ブログパネルにDomain・kind単位のprefixを追加。既定値は
`/diary`・`/blog`。`/`も指定可能。設定変更は既存Pathを移動しない。
- 「新規ページ」は日付・任意keywordを指定するダイアログを開く。
`{prefix}/yyyy/mm/dd` または `{prefix}/yyyy/mm/dd/{keyword}` をサーバーで
検証し、書き込み権限とPathの不存在を確認してエディタへのリンクを返す。
日本語keyword可。keywordは単一要素とし、traversal・制御文字・URL区切りは拒否。
- エディタを別タブで開き、本文保存後に元のダイアログから記事登録へ進む。
この任意の従来フローは二段階操作。新規記事ダイアログでは一括保存できる。
計画APIはPageを作成・予約しない。確認後に別の操作が同じ
Pathを作成した場合、既存エディタはそのPageを開くため、排他的な新規作成保証は
専用の原子的投稿APIが提供する。計画APIは自動上書き・自動登録を行わない。
- keywordなしのPageとkeyword付きの子Pageは同日に共存可能。
`idx_diary_owner_date`はschema初期化で削除し、既存データは保持する。
- Domain設定のトップページ形式に日記/ブログを追加。`home_layout=diary|blog`
は認証後の `/` で直接一覧・カレンダーを描画する。日付選択は以下のviewer Pathへ
進む。従来の `/v/diary`・`/v/blog` は残す。既存home_pathを削除しない。
- 配置先の表示名を「配置先」に短縮。物理的なInstance FQDN・fingerprintと
home_layoutは別設定のままとし、別Domainの記事や権限を暗黙に共有しない。
- 匿名公開処理は従来の承認済みPage/ディレクトリ表示を維持する。
home_layout設定で記事メタデータを公開しない。設定済み射影の匿名カレンダーは
上記の公開Path/Revision由来データのみで構成する。
- Domain一覧の歯車「ドメインの入口設定」からトップページ・日記/ブログの有効状態・
prefixを一括指定できる。配置先そのものは既存のDomain更新フォームで指定する。
初回ダイアログは現在の設定値を引き継ぐ。保存後はこのパネルを設定の正本とし、
homeパネル/個別プラグインの設定APIからの競合する更新を拒否する。
### コントローラからの配信
- `domain_entry_settings(domain_uuid,settings_json)`が明示的な入口設定を保持。
Campus管理者のみ更新可能。外部キャンパス管理下ではローカル更新不可。
設定検証・管理権限確認・保存・ローカル配置への反映は同一transaction。
- 署名付きCampus manifestに`domain_entries`を追加。明示設定がある場合だけ
schema_version=2を使用し、設定のない従来manifestはversion=1のままとする。
入口設定も署名・内容hash・revision更新の対象。対象CampusのDomainのみ含める。
- 受信時はDomainの所属・Layout列挙・prefix・選択したプラグインの有効状態を検証。
Domain snapshot、入口設定、local配置のhome_layout/periodical設定、受信checkpointを
同じtransactionで更新する。remote配置のDomainには実行設定を有効化しない。
- 記事本文・記事登録・公開承認・資格情報・任意configは配信しない。
prefix変更も記事移動を発生させない。同一revisionの再送は従来どおり冪等。
- v2非対応ノードは同期を拒否するため、**配置先を先に更新してから**入口設定を保存する。
enrollmentで`manifest_version=2`と専用の`capability_signature`を送信し、
インスタンス鍵で署名した`normalized FQDN + LF + token + LF + manifest=2`を検証する。
従来のenrollment署名も併せて必須。古いクライアントの申告なしはversion=1として扱う。
- `federation_instance_capabilities(instance_uuid,manifest_version)`で鍵identity単位に
能力を記録。FQDNが同一でも鍵変更は別の申告・承認が必要。
Campus manifestは全承認済みノードに渡るため、一台でもv2未確認なら入口設定保存を
409で拒否し、ダイアログにも案内を表示する。受信側は従来どおり署名・versionを検証し、
設定を削ったv1へ黙ってフォールバックしない。
- capabilityは対応機能の申告であり、稼働状態・実際の反映完了の証明ではない。
enrollment更新時に申告がなくなればversion=1へ戻す。署名は既存enrollment同様
token期間中のproofでありnonce付きの鮮度証明ではない。反映ACK/鮮度管理は後続。
- manifestで設定が省略された場合は設定解除を意味しない。既存設定を保持する。
現段階では管理を解除する操作はなく、Wiki形式への変更・各プラグインの無効化も
入口設定パネルから明示的に行う。削除Domainの設定保持/GCは後続。
### 日付ナビゲーションの正規URL
- 月別:`GET /v/{diary|blog}/yyyy/mm`。
- 日別:`GET /v/{diary|blog}/yyyy/mm/dd`。
- 自分の記事:存在フラグ`?own`。カテゴリは`?category=...`、ページ送りは
`offset`を維持する。組み合わせは`?category=Work&own`。
- `/v/blog`は全期間、`/v/diary`はDomain timezoneの当月。
- 旧`month`/`date`/`mine=1`は認証確認後、302で正規URLへ転送する。
date単独でも対象月を導出する。矛盾する日付、存在しない日付、重複した日付query、
桁数不正は400。未知のHTTPメソッドを許可せず、現段階はGETのみ。
- カテゴリ/ownは月移動・日付選択・ページ送りで保持する。フィルタフォームの
再適用は日付選択とoffsetをリセットし、指定月(ブログは全期間も可)から表示する。
- 専用ドメインの `/` は入口。`/yyyy/mm/dd`は通常Pageの本文を置けるため、
日付別一覧をそこへマウントしない。月・日への移動は`/v/{kind}/...`を使用する。
- 新規投稿計画APIの`date`は記事作成パラメータであり、閲覧URLの日付queryとは別。
将来のQUERY対応はTODO。現段階ではルータや認証middlewareに追加しない。
## データモデル
- `periodical_settings(domain_uuid, kind, enabled)`:Domainとプラグイン単位の有効状態。
- `periodical_prefixes(domain_uuid, kind, prefix)`:投稿先prefix。未設定時はkind別既定値。
- `periodical_entries(domain_uuid, kind, page_uuid, owner_uuid, local_date,
title, category, timezone, version)`:正本はPage UUIDで参照する。Pathは保存せず
閲覧時に現在のbindingから解決する。renameで日付・カテゴリが失われない。
- `periodical_events(id, domain_uuid, kind, page_uuid, actor_uuid, operation,
version, created_at_ms)`:設定/登録/解除と同一transactionで記録する変更journal。
本文・タイトル・資格情報は複写しない。これは共通outbox配送や通知機能そのものではない。
本文はDocument Storeと既存Revisionにのみ保存する。登録解除はメタデータだけを
外し、Pageを削除しない。最後のPathがなくなったPageは一覧から非表示になる。
メタデータの孤立行のGC・完全消去・履歴保持期間は後続の保持ポリシーで扱う。
日付は明示したcivil date(YYYY-MM-DD)であり、UTC時刻への暗黙変換をしない。
作成時のDomain timezoneをサーバーで記録する。設定timezone変更後も過去の記事を
別日に移動しない。未来の日付を指定しても公開予約や時刻による自動公開は行わない。
著者は最初の登録時の認証済みPrincipalで固定し、クライアントのowner指定は信用しない。
## 権限と公開範囲
- 登録情報を利用するUI/APIは**認証必須**。legacyモードでも匿名メタデータ一覧を
許さない。設定済み射影の公開Path/Revision由来一覧は上記の限定例外。
- 設定変更はactiveなDomain管理者グループのowner/manager。
- 記事登録・情報更新・解除は対象Pathのwrite権限と上位Locality制限を再検査する。
`upload_only`や`read_write_once`だけでは、既存Pageの記事情報を書き換えられない。
既存エディタと同じく、本人の `/u/{username}` Wiki配下は本人の編集権限で扱う。
この場合もactive membership・実際のidentity・上位Locality制限を検査する。
- 一覧・カテゴリ・カレンダー件数・最近の記事・ページ送りは、現在のPage閲覧権限で
絞った後に構築する。非公開の別名で先にdedupeして可視Pageを失わない。
- 登録操作は匿名公開承認ではない。Page本文の匿名公開は従来の正確なRevision承認に
従う。登録タイトルのみPageの公開状態を継承し、それ以外は個別の承認契約が必要。
- 下書き/公開/予約公開を、この登録テーブルの有無や日付と混同しない。
公開一覧・RSS/Atomには記事メタデータの承認されたスナップショットと失効検査が必要。
変更transactionは最初にSQLiteのwrite予約を取得し、active membership、設定、Pathの
Page UUID、write grant、group/locality caps、期待versionを同一snapshotで検査する。
既存記事の変更にはPage UUIDも要求し、renameやPathの再bindを検出する。
削除・再登録後もjournalからversionを引き継ぎ、古い編集要求の再利用を拒否する。
古いversionによる登録更新は409で明示し、上書きしない。同日複数記事は許可する。
## APIと負荷上限
`/_/api/v1/extension/content.{diary|blog}/{settings|entries}`:
- `GET settings`:有効状態。`POST settings`:`{enabled: bool}`。
GETはprefixも返す。POSTは任意の`prefix`を受け、有効状態・prefix・journalを
同一transactionで保存する。prefix省略時は既存設定を維持する。
- `GET plan?date=YYYY-MM-DD&keyword=...`:認証・有効状態・対象Pathのwrite権限を
確認し、未使用Pathとeditor_hrefを返す。既存Pathは409。POSTは不可。
- `GET entries`:現在読める記事のメタデータのみ。
- `POST entries`:`path,title,date,category,version`(新規は0)。更新/解除は
`page_uuid`と現在のversionを付け、解除には`remove:true`を指定する。
- 未定義メソッド・未知フィールド・複数JSON値は拒否。本文上限8 KiB。
- UIは20件単位、最近の記事は8件。索引取得は本文を読まない2秒のmetadata query、
最大5,000 binding行/4 MiB。超過時は黙って結果を欠落させず503。
設定・更新transactionは3秒。UIの編集権限評価は表示中の最大20件だけ。
- 初期版はpermission-filtered keyset pagingではない。大規模サイト向けには上限を
単純に広げず、バッチ権限評価・索引分割・不透明cursorを先に実装する。
- ブラウザ側に記事や権限を永続キャッシュしない。BFCache復帰時に再読込。
設定パネルは表示された時だけ非同期で読む。fetchは15秒で打ち切る。
## 次の実装/TODO
- [x] Page+初回Revision+記事情報を原子的に作成するMarkdown投稿フォーム。
既存の本文保存・asset固定とjournal、冪等再送を実装。
- [ ] 投稿journalから共通outboxへの配送、City自動生成・通知、receipt保持期間とGC。
- [x] 同一Campus・同一インスタンスの参照型一覧/カレンダー射影と双方の読取権限検査。
- [x] 承認済みPath/Revision由来の匿名射影一覧・カレンダー。
- [x] 専用ドメイン内の記事本文、登録タイトル、同月/前後ナビゲーション、RSS 2.0。
- [ ] タイトル以外の登録メタデータの匿名射影承認、別インスタンスの
参照設定配信と認証付き取得・失効、クロスDomain SSO。
- [x] Domain入口設定ダイアログと署名付きmanifest v2による設定配信・原子的反映。
- [x] 署名付きcapability申告・全承認済みノードのv2事前確認・UI案内。
- [ ] Domain新規作成フォームとの一体化、設定の管理解除・GC、配信反映ACK/鮮度管理。
- [ ] 残りの記事メタデータの公開承認・Atom。承認ポリシー/Inboxと接続し、
Pageや上位階層の公開範囲を広げない。タイトル変更・公開撤回で即時失効。
- [ ] 本文抜粋、表紙、複数カテゴリ/タグ。
- [ ] 個人/共有コレクション、著者選択、所有者移管/引き継ぎ。
- [ ] コメント基盤と最近のコメント:閲覧制限、モデレーション、削除・通知を共通化。
- [ ] tDiary取り込み:提供サンプルと公式仕様を確認して対応版/形式を固定する。
Ruby/eval/Marshalの任意実行は禁止。既存import session/journalを使い、事前確認、
日付・timezone・旧URL・セクション・添付・コメントの対応、再開・重複防止を実装。
移行著者は出典であり、ローカル認証ユーザーと偽って紐付けない。
- [ ] 共通outbox・保持/export/削除ポリシー・metadata履歴、孤立メタデータのGC。
- [ ] 索引のkeyset pagingと負荷試験、外部拡張の署名・分離runtimeは別途。
検証:登録/更新/解除、同日複数記事、うるう日、write拒否、Domain越境、グループ失効、
rename追従、非公開カテゴリ/件数の漏えい、journal失敗時のrollback、version再利用、
無効化時のデータ保持、厳格JSON、匿名拒否、PC/モバイルでの設定と登録操作。
+244
View File
@@ -0,0 +1,244 @@
# Domain Namespace and Federation
## Decisions
### Paths are Domain-local
A semantic path is identified by the pair:
```text
(domain_uuid, normalized_path)
```
Therefore `/handbook` in the Sales Domain and `/handbook` in the Engineering
Domain are different bindings and do not conflict.
The `paths` table uses a composite primary key:
```sql
CREATE TABLE paths_v2 (
domain_uuid TEXT NOT NULL,
path TEXT NOT NULL,
object_uuid TEXT NOT NULL,
created_at INTEGER NOT NULL,
is_primary INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (domain_uuid, path)
);
```
Existing rows are assigned to the current default Domain during migration.
All path reads and mutations must receive the request Domain UUID explicitly;
silently using a process-wide default is prohibited in request handlers.
### Objects are instance-global
Page Objects are not owned by a Domain. Their UUID is globally unique within
an instance, while a Domain owns bindings from its paths to Object UUIDs.
This preserves the MagicPage property:
```text
sales.example.test/guide ─┐
engineering.example.test/guide ├─> Page UUID 7a…
support.example.test/runbook ─┘
```
Revisions, immutable Documents, tags, and assets remain attached to Object
identity. Authorization may still restrict which Domains may bind or expose
an Object.
If stronger tenant isolation is later required, it belongs in policy and
storage-placement layers rather than by weakening UUID identity.
## Link addressing
Links have two forms:
- Same Domain: a root-relative semantic path such as `/guide`.
- Another Domain or another instance: an absolute URL containing the
destination FQDN, such as `https://engineering.example.test/guide`.
A cross-Domain link must not be stored as a bare `/guide`, because its meaning
would change with the request Host. Internally, a locally managed destination
may additionally retain `domain_uuid` for rename tracking, but its rendered
and exported form is still an absolute URL.
Object addresses (`uuid:`, `rev:`, and `asset:`) are local-instance addresses.
To address another instance they require an origin:
```text
https://engineering.example.test/o/uuid:…
https://engineering.example.test/o/rev:…
```
No request should transparently resolve a remote UUID against the local
SQLite database.
## Local and remote Domains
A configured FQDN does not by itself mean that a Domain is remote. One
PagesWiki instance may serve several local FQDNs. Domain placement therefore
must be explicit:
| placement | Meaning |
| --- | --- |
| `local` | This instance serves the Domain and owns its path namespace. |
| `remote` | The Domain is a catalog entry served by another instance. |
A remote Domain has no writable local path namespace. Its origin is derived
from its owning Campus FQDN and Domain host. Proxying remote content is not
implicit.
Implemented additive Domain fields:
```sql
placement TEXT NOT NULL DEFAULT 'local',
```
The URL scheme is transport policy and is not part of Campus or Domain
identity.
## Host resolution
Campus stores an FQDN without `http://` or `https://`. A Domain host resolves
as follows:
- empty host: the Campus FQDN;
- label without a dot: `label.<campus-fqdn>`;
- host containing a dot: the host is already an FQDN and is used unchanged.
Resolution is exact. An unknown request Host does not fall back to an
arbitrary default Domain. The Domain with an empty host is selected only when
the request Host equals its Campus FQDN.
## Campus authority modes
Campus configuration has an explicit authority mode:
| mode | Responsibility |
| --- | --- |
| `standalone` | All Campus and local Domain configuration is maintained on this instance. |
| `controller` | This instance is authoritative for a Campus topology and publishes desired configuration for managed instances. |
| `managed` | This instance accepts topology configuration from one external Campus controller. Local topology edits are disabled. |
Implemented additive Campus fields:
```sql
authority_mode TEXT NOT NULL DEFAULT 'standalone',
fqdn TEXT NOT NULL
```
The FQDN identifies the Campus in every authority mode. A controller Campus
may contain both local and remote Domain records. A managed instance stores
the controller Campus UUID, FQDN, and Domain UUIDs unchanged.
A Domain owned by a controller Campus also records `instance_fqdn`. This is
the concrete PagesWiki instance selected to serve that Domain. Controller
Domains require this value; standalone Domains default it to the Campus FQDN.
Managed instances treat Domain topology as read-only because those records
are reconciled from the controller.
Controller instances issue random enrollment tokens. Only a SHA-256 token
hash is stored by the controller, and the plaintext token is displayed once.
A joining instance presents the token, its FQDN, and the SHA-256 fingerprint
of its persistent Ed25519 public key.
The enrollment request includes that public key and a signature over the
normalized instance FQDN and enrollment token, so the controller verifies
proof-of-possession before recording the fingerprint.
Registration creates a pending instance. An administrator verifies its
fingerprint and approves it before it becomes available in the Domain
placement selector. The placement stores both the instance FQDN and
fingerprint. Re-registering the same FQDN with a different fingerprint
creates another pending identity and never inherits the old approval.
Pending instances receive Campus metadata but no Domain assignments. Revoking
an instance disables Domains assigned to that exact FQDN and fingerprint.
Enrollment tokens are individually revocable.
An external Campus is initialized with:
```text
pageswiki --add-external-campus CAMPUS_FQDN TOKEN
```
Development environments may explicitly select unencrypted transport with
`--add-external-campus-http CAMPUS_FQDN TOKEN`. HTTP is never selected
implicitly; the standard command always uses HTTPS.
Either enrollment form may be combined with `--no-default-campus` for a
dedicated managed instance. Its bootstrap standalone Campus and Domain remain
available while enrollment or approval is pending, and are removed
transactionally after the controller assigns the first enabled Domain.
`PAGESWIKI_INSTANCE_FQDN` supplies the joining instance FQDN. Enrollment
fetches and applies the controller Campus name, title, default language,
FQDN, and Domain snapshot. These fields are read-only locally. The token is
stored under the data directory with mode `0600`; the instance Ed25519 private
key is also stored with mode `0600`.
The Managed Campus Save action performs a Controller health probe without
making inherited fields editable. The management view displays a yellow-green
lamp after a successful probe and a red lamp after failure. The transport
(`https` or explicitly selected `http`) is retained from enrollment. Delete
detaches the Managed Campus, its Domain projections, Domain settings, and
Path bindings; Page Objects and immutable Revisions remain intact.
## Domain-scoped settings
Campus and Domain topology are instance-level administration. All other
settings use `(domain_uuid, key)` identity. This includes locale, timezone,
theme, home path, editor behavior, navigation, and
maintenance preferences. Legacy settings are assigned to the default Domain;
new Domains start with product defaults.
The displayed Wiki name is not an independent setting: it is always the
resolved Domain title. Recent Objects are selected by Domain Path bindings.
The administration view may inspect another Domain through an explicit
Campus and Domain selector.
## Configuration distribution
Federation is desired-state synchronization, not shared SQLite access.
The preferred flow is:
1. A controller publishes a versioned, signed Campus manifest.
2. A managed instance authenticates with its enrollment token and pulls the
manifest.
3. The instance validates schema version, Campus UUID, allowed hostnames, and
monotonic manifest revision.
4. It applies the manifest transactionally.
5. It reports the applied revision and validation errors.
Pulling avoids requiring inbound administrative access to every managed
instance. A push notification may trigger a pull, but does not contain
authoritative configuration itself.
The manifest controls topology and presentation defaults only. It must not
carry SQLite files, revisions, Documents, local secrets, OIDC client secrets,
Macaroon root keys, or instance-private signing keys.
## Security requirements
- Transport security policy is evaluated separately from the stored FQDN.
- Controller manifests require signature verification and replay protection.
- A managed instance is pinned to one Campus UUID and controller identity.
- Hostname changes require explicit allow-list validation.
- Local emergency override and last-known-good rollback are retained.
- Controller unavailability does not remove the last applied configuration.
- Remote links are rendered as external navigation, never server-side fetched
merely because a page contains the link.
## Migration order
1. [x] Add placement and authority metadata. Remote Domains have no local
writable Path namespace, and managed Campus topology is read-only.
2. [x] Rebuild `paths` with `(domain_uuid, path)` identity and assign legacy
rows to the default Domain.
3. [x] Thread Domain UUID through Store APIs, server handlers, recursive
operations, browser/tree queries, and the data CLI.
4. [x] Add cross-Domain absolute-link helpers and tests.
5. [x] Add signed controller manifests and managed-instance reconciliation.
Steps 2 and 3 shipped together. Adding `domain_uuid` while leaving unscoped
queries would have created cross-Domain data disclosure.
+91
View File
@@ -0,0 +1,91 @@
# Event Scheduler
## Purpose
CPU-, memory-, and decoder-heavy work must not execute in Viewer requests.
PagesWiki uses a persistent SQLite event queue for deferred work.
`event_jobs` records:
- event UUID and type
- idempotency key
- JSON payload
- `queued`, `running`, `succeeded`, or `failed` status
- scheduled time and attempt count
- latest error
- creation and update timestamps
The current implementation is a single scheduler loop that may run up to the
configured concurrency in goroutines. It checks foreground request activity
between claims and keeps one reserved background slot so a long-lived editor or
stream cannot starve all jobs. Cross-instance leases are still future work. The
transactional Domain outbox now records Page/Revision creation and Path/Object
mutations. Domain-local consumer watermarks are durable and monotonic;
notification delivery remains future work.
External preview tools run through bounded
commands with timeouts.
## Event log retention and trends
`event_logs` remains the recent, drill-down log. Each record is associated with
its event type when the job is known. `event_log_policies` provides per-event
retention, aggregation window, bucket size, and maximum raw-row settings; `*`
is the safe default. `event_log_buckets` stores compact counts and first/last
timestamps by event type, level, and time bucket, so trend charts do not scan
the raw log table. The API exposes `/event/logs/trends` and `/event/policies`.
Retention removes old rows in place and keeps bounded aggregate buckets. A
future partition/rotation implementation may replace the physical table, but
must use an atomic rename-and-recreate procedure; an online `DROP TABLE` is
never used while workers can append logs.
## Preview Events
`preview.generate` uses the immutable Document hash as its idempotency key.
Viewer never generates a thumbnail. A children projection:
1. checks the immutable preview cache;
2. emits the cached thumbnail URL when present;
3. otherwise enqueues the event and immediately renders a format icon.
The browser polls only the lightweight cache URL for visible entries. Once the
job succeeds, it replaces the icon with the cached image without reloading the
Page.
Current generators:
| Input | Generator | Cached form |
| --- | --- | --- |
| PNG/JPEG/GIF | bounded Go image resampler | JPEG |
| PDF | `pdftoppm`, first page | JPEG |
| Video | `ffmpeg`, one frame | JPEG |
| Excalidraw | bounded server SVG renderer | sandboxed SVG |
Individual PDF pages use the same queue. A cache miss returns `202` with
`Retry-After`; the browser retries until the scheduler writes the immutable
`<document-hash>-p<page>.jpg` file. PDF page counts and non-ZIP archive listings
are persisted output of `projection.metadata.generate`, not Viewer work. See
[deferred projection metadata](projection-metadata-cache.md) for cache quotas,
pending/retry responses, authorization, and decoder limits.
Generated files live beside the Document Store in `previews/` and are addressed
by immutable Document hash. Cache responses are immutable for one year.
## Scheduling
- Missing previews are enqueued when an icon projection encounters them.
- A periodic sweep runs every 15 minutes.
- The first sweep runs shortly after startup.
- Configuration → Execution monitor combines resource charts with running jobs
only. Job history & logs contains paginated completed jobs and per-job logs.
Event definitions exposes the manual “Generate missing previews” trigger.
See [Configuration panels](configuration-panels.md) for polling, indexed queue
listing, lazy log retrieval and legacy resource-panel URL compatibility.
Failures remain visible in scheduler statistics and logs. Retry/backoff and
cancellation are persisted in the queue; a later sweep or manual trigger may
enqueue a missing cache again. Preview requests never execute the generator in
the normal Viewer request path. Non-ZIP entry extraction remains a bounded
foreground stream pending its separate cached-entry design; metadata listing
and PDF page counts have migrated to deferred projections.
@@ -0,0 +1,78 @@
# Signed Campus manifest integrity
Implemented bounded single-writer-SQLite correction, 2026-09-14. This is not
controller HA, key rotation, multi-node metadata fencing or a new federation
trust protocol.
## Controller sequence allocation
`BuildSignedCampusManifest` canonicalizes the supplied Domain list by UUID,
rejects duplicate/missing identities and hashes the Campus plus filtered Domains.
A single SQLite `INSERT ... ON CONFLICT DO UPDATE ... RETURNING revision`
allocates the sequence against the current persisted hash:
- First content gets revision 1.
- Identical content retains its revision and timestamp.
- Changed content atomically increments the previous revision.
- Database errors and integer overflow fail, never resetting to revision 1.
The returned revision is signed with the existing Ed25519 identity. Concurrent
calls cannot sign different content with the same revision. Ordering-only changes
to the supplied Domain list do not churn revisions. This orders supplied
snapshots; it does **not** make the caller's earlier Campus/Domain reads a
transactional configuration snapshot. A controller-wide configuration generation
is still needed before claiming DR/HA or preventing an old caller snapshot from
being issued later with a newer revision.
## Managed-instance application
Verify signature, schema, Campus identity and Domain identity/hostname shape
before acquiring a database write reservation. Then, in one transaction:
1. Reserve SQLite's writer with a no-op update to the manifest-state table.
This works even for a first enrollment with no row; competing first pins
serialize instead of both reading an absent checkpoint.
2. Read the pinned fingerprint, applied revision and exact payload. Only
`sql.ErrNoRows` means an unpinned Campus. Other database errors fail closed.
3. Reject changed signing identity, lower revisions and a reused revision with
different payload. An exact duplicate succeeds without reapplying the snapshot.
4. Check authority ownership and apply the Campus/Domain snapshot using the
transaction-owned helper. Update placement/default locale as before and keep
`projectCampusAdminMembershipsTx` in this same transaction.
5. Persist the verified public key/fingerprint, revision and payload checkpoint;
commit all snapshot, inherited-permission and checkpoint changes together.
A checkpoint/projection/domain-write failure rolls everything back, including a
new trust pin. Retrying the same manifest after a rolled-back failure is safe.
No failed/replayed manifest silently retries with relaxed verification.
## Authority and legacy compatibility
A valid signature establishes a signing identity, not authority over every
local UUID. A managed snapshot cannot replace a standalone/controller Campus
or reparent a Domain UUID owned by another Campus. A new managed Campus and
updates to its own Domains remain supported, including initial pending enrollment
followed by an approved manifest that deploys Domains to the matching instance.
The legacy unsigned snapshot entry point still permits enrollment/resynchronizing
an **unpinned** managed Campus. It acquires the same writer reservation before
checking the pin. Once a signed checkpoint exists, unsigned fallback is rejected;
omitting a manifest can no longer bypass signing-identity/replay checks. Explicit
trust reset or key rotation needs a separate administrator-controlled workflow.
Initial enrollment remains trust-on-first-use through the configured controller
and enrollment transport; signing does not make an HTTP bootstrap resistant to
an active network attacker.
## Verification and remaining work
Tests cover 20 concurrent same/changed-content sequence allocations, canonical
ordering and overflow, 24 concurrent duplicate/out-of-order deliveries, competing
first keys/payloads, injected initial/updated-checkpoint and inherited-projection
failures, missing state tables, a one-connection pool, cross-authority collisions,
legacy-to-signed upgrade, approved placement/locale inheritance and unsigned
downgrade rejection. Existing managed enrollment/reconciliation tests remain in
the suite.
There are no new tables, shared keys or schema migrations. Key rotation, explicit
global authority transfer, independently versioned instance projections, bounded
configuration capture and DR/HA are follow-ups rather than implied guarantees.
+536
View File
@@ -0,0 +1,536 @@
# September 2026 execution ledger
User direction: continue the remaining roadmap in priority order; defer extremely
complex/high-risk changes with explicit prerequisites. Preserve existing identity
and deployments. This ledger separates completed slices from unresolved gates.
## Active batch
### Japanese design consolidation and Wiki publication (2026-09-19)
- Added a 22-chapter Japanese handbook plus index, separating current behavior,
proposals, unresolved choices and historical claims. Original source documents
remain unchanged in identity/location; a source inventory maps them to chapters.
- Expanded Organizer/tasks/tickets, calendar/contacts/DAV, RSS/FreshRSS/newsboat,
IMAP capture and incremental HTML editing proposals with identities, authority,
conflict/retention behavior, delivery slices and acceptance fixtures. No new
external integration or connector is enabled by this design work.
- Reviewed primary RFC and FreshRSS/newsboat documentation; runtime/client
compatibility remains a prerequisite, not a claimed implementation.
- `tools/design-export` renders with the application Markdown renderer, validates
internal chapter links and emits source/payload hashes. Tests cover tables,
chapter count, bad links and staging overwrite refusal.
- Uploaded 23 new `ja` Page revisions through the trusted local data CLI to
`https://pages.anya.jp/lab/pageswiki-dev/`; destination was empty beforehand.
Read-back comparison and manifest/DB hash checks passed for all 23 payloads.
Receipt: `publication-ja-2026-09-19.json`. Existing English sources are retained.
- Anonymous HTTPS access still redirects to login. No publication/authorization
settings, external credentials, application runtime or deployment were changed.
`go test ./...` and diff checks passed.
### Scoped automatic publication and compact blog index (2026-09-19)
- Added explicitly confirmed Street/Spot automatic publication, live revision and
publisher-authority checks, inherited manual-approval boundaries, ACL/alias
exclusions, and versioned impact previews. Existing settings stay unchanged;
no production locality is opted in by this deployment. See
[automatic publication](automatic-publication.md) for limits and remaining work.
- Blog/diary and projected public indexes use compact date/title tables. The month
selector sits above the sidebar calendar; authenticated row actions remain
accessible through labelled icons. Existing post editing and public article
navigation are preserved.
- Full Go tests, vet and diff checks passed. Opt-in Chromium coverage passed for
automatic publication, City governance, periodicals and public projection.
- Follow-up: month input, apply and reset form a single compact row; SVG buttons
have localized tooltips/accessibility labels. Desktop/mobile browser tests
enforce single-line controls and placement above the calendar.
- Pre-migration online backups of both databases passed quick checks under
`/home/anya/.cache/pageswiki-backups/pre-auto-publication-kv0VzP/`.
- Deployed app2 then app with image
`sha256:8ca7973bb12126ba2291dc9e6e1c9a4c5faad77ff92b56cf4f79ee69e9620523`.
Both instances responded successfully with zero restarts; app is healthy.
Public HTTPS serves the compact index and three RSS embedded article bodies;
both databases still contain zero automatic-publication rules. Production mobile
rendering confirms the one-line month controls. Anonymous source editing still
redirects to login.
- Future tasks/tickets, organizer/DAV, mail ingestion and HTML editing ideas are
recorded in [design backlog](organizer-and-editing-ideas.md), not implemented in
this batch. Full WYSIWYG remains an explicit undecided design choice.
### Full-content RSS, standalone composition and X sharing (2026-09-19)
- RSS `content:encoded` uses the inert HTML pipeline, namespace-aware XML/CDATA,
absolute public article/image/anchor URLs and exact live Revision rechecks.
Limits: 20 articles, 1MiB input/article, 8MiB total HTML, 5s generation; HEAD skips
body work. RSS-reader copies cannot be remotely recalled after unpublishing.
- Added authenticated GET-only `/v/blog/-/new` and `/v/diary/-/new`, themed responsive
forms backed by the existing atomic posts API. Projection targets redirect to the
configured source composer. No GET creates content; disabled plugins return 404.
- Post completion offers X Web Intent with title and registered projection-domain
URL; multiple eligible Domains are selectable. Invalid/disabled/cross-Campus
projections are excluded, and pending publication is explicitly warned/confirmed.
No external posting occurs without user action; no OAuth secrets or new grants.
- Added namespace/CDATA, absolute link, unsafe HTML, composition route and share-
domain/prefix regressions; Chromium covers standalone posting and sharing controls
at desktop/mobile widths without navigating to X or creating production content.
- Full Go tests, vet, JS syntax, diff check and opt-in Chromium suites passed.
Deployed app2 then app with image
`sha256:f51dadce7481b480bdd924ad65d050e6d9570a37081c91a7cd5562394d9be4bc`.
HTTPS RSS returned 200 with three embedded public HTML bodies and the content
namespace; article returned 200 with target-domain OGP URL; both new-entry routes
redirected anonymous requests to login (303). app healthy, both containers running
with zero restarts. No production article creation or X posting was performed.
### Dedicated public blog articles and RSS (2026-09-19)
- Dedicated diary/blog Domains now project approved source article bodies at
`/YYYY/MM/DD[/keyword]`. Header/browser title use target Domain branding; article
pages keep month calendar, other entries that month and older/newer navigation.
Known public article links in sanitized bodies are remapped to the target host.
- Registered titles explicitly inherit the Page's live publication status. This
changes the earlier h1-only index contract at the user's request. Private category,
author and registration date are still omitted; dates derive from approved Paths.
No registration table writes, grant changes or migration are needed.
- `/rss.xml` emits RSS 2.0 with up to 20 public titles, target-domain links/GUIDs and
Revision timestamps. HTML advertises the feed. No private metadata or body copies
in RSS; no shared HTTP caching. Subscriber-retained copies cannot be revoked.
- Full Go tests, vet, diff check and Chromium tests at 1440/390 px passed. Tests cover
keyword routes, domain title, escaped registration titles, sanitized body, previous/
next links, feed XML, private entries, edited-revision revocation and both auth modes.
- Remaining: Atom, excerpts/covers, publication approval of other metadata, cross-
instance projection and SSO. Non-public embedded assets do not gain public access.
- Deployed app2 then app with
`sha256:2a9743aadf687dedb7465b6e9c22f313818aa59fe341a94c5c6ec82c139386cf`.
Anonymous HTTPS index, `/2026/09/17` and `/rss.xml` all returned 200 (one published
entry); parent editor still returned login 303. Confirmed registered Japanese title,
sanitized body, blog Domain header and calendar in
`/tmp/pageswiki-blog-article-review-0919.png`. app healthy; publication count remains
one and enforcing config unchanged. No production content/config writes were made
by this task; current Object count is 1456 (live instance continues background work).
### Public diary/blog projection index (2026-09-17)
- Root cause: configured projection views always required a session, even with
approved publications in the source prefix. Added anonymous root/month/day views
in enforcing and legacy target modes, using only the source's live publication
manifest. Source authorization mode must remain enforcing.
- Dates derive from approved Paths; headings from approved HTML, bounded to 64KiB
for at most 20 displayed and 8 recent entries. No private article metadata,
categories, authors, editor dialogs or unrelated navigation is exposed.
- No grants, auth modes, schema or content changed. Body links remain on the source
host. Source disablement, invalid credentials and publication revocation fail
closed. Registration metadata approval and same-host body projection remain TODO.
- Validation: full `go test ./...`, `go vet ./...`, JS syntax, diff check and existing
Chromium periodical flow passed. New tests cover both target modes, private
registration metadata, unapproved Paths, invalid credentials and edited revisions.
- app2 then app deployed with image
`sha256:36f5fba8a86db9ed6ea94872400bc86745c6499e3c09b49c11896303a953d86f`.
Anonymous HTTPS root/day views on blog.pages.anya.jp returned 200 with exactly one
approved article; source article returned 200, parent editor and invalid credentials
returned login 303. Browser screenshot checked at
`/tmp/pageswiki-public-blog-review.png`. app healthy, both running without restarts.
Object/publication counts remained 1455/1; authorization configuration unchanged.
### Domain entry dialog CSS correction (2026-09-17)
- Root cause: the modal was nested in a dense administration table cell. Broad
descendant selectors made forms inline-flex, help paragraphs inline, and controls
inherit compact table sizing. Previously the browser test checked `open` but not
actual geometry (a hidden panel ancestor could still conceal the dialog).
- Moved modals outside tables and panels into the body. Added isolated responsive
fields, block help text, themed controls, toggle labels, sticky header/close button,
background scroll lock, accessible dialog title and CSS cache-version update.
- New Chromium regression checks at 1440/390 px with Light/Nanoha Dark: visible
viewport bounds, no horizontal overflow or overlapping controls, form/help display,
sticky close button and close/reopen. Screenshots inspected under
`/tmp/pageswiki-domain-entry-review/`. Existing periodical browser flow, full Go
tests, vet and diff check passed.
- UI-only release; no schema/content/permission changes or database restore.
app2 then app updated to
`sha256:d2cb4a02e780790294245e60a394e6046be1f3160bc9e4186c0daf7f9a8a4369`.
Both health endpoints responded, zero restarts; served config.css matches source.
### Local diary/blog projection deployment (2026-09-17)
- First slice: same-Campus, local-placement metadata projection, source-prefix
filtering and source+destination read policies; no copied content. Article/body/edit
links open the source Domain. No anonymous, cross-instance or host-preserving body
projection yet. Local projection settings are not in federation manifests.
- Backup directory `/home/anya/.cache/pageswiki-backups/pre-periodical-projection-aw54pH/`:
app.sqlite and app2.sqlite, private permissions, both quick_check OK.
- app2 then app deployed with image
`sha256:e44fbb1a55f7eef4a4c4fec08a87efa8bc7e592f222c99090930c95590d435cf`.
Main DB initialization briefly left the listener unavailable during restart;
final app health=healthy, app2 health endpoint OK, zero restarts, public HTTPS=200.
Running template contains the domain-projection settings forms.
- Full tests, vet, diff check, focused race and desktop/mobile Chromium passed.
Fixture tests cover no-copy behavior, source ACL denial/revocation, prefix filter,
source links, target write rejection, self/cycle/cross-Campus rejection and remote
source fail-closed behavior.
- Production Objects=1454, publication entries=4, matching pre-update counts.
No production projection bindings were created automatically; user chooses source.
### Diary/blog and Domain entry deployment (2026-09-17)
- User explicitly authorized backup and deployment. Online SQLite backups:
`/home/anya/.cache/pageswiki-backups/pre-domain-entry-6a73yw/app.sqlite`
and `app2.sqlite`, directory private / files 0600; both `PRAGMA quick_check=ok`.
- Deployed accumulated date-path navigation, atomic article composer, Domain
entry-settings gear/dialog and signed manifest v2 to app2 first, then app.
- Continued implementation: signed manifest capability proof in enrollment;
unknown/legacy approved peers block entry-setting updates with 409 and UI guidance.
The check covers all approved Campus peers because they share a Campus manifest.
- Final running image on both instances:
`sha256:0dbcb4aacbc924855f0b686a859bd10c7932eea9d1736fc9f4be9a6337b694ae`.
app healthy, app2 running, zero restarts; Host-routed health checks both OK.
`https://pages.anya.jp/` returned 200. Served periodicals.js hash matches source.
Running template includes `data-domain-entry-open`; authenticated gear/modal and
posting interactions were exercised in isolated Chromium fixtures, not by creating
production administrator sessions.
- Actual approved ext-node enrollment reports manifest_version=2. Old pending
fingerprint remains pending; no approval or identity changes were made.
- Main DB before/after: 1454 Objects and 4 publication entries. No entry settings,
article content, user roles or publication grants were changed during deployment.
- Tests: full `go test ./...`, vet, diff check, browser fixtures at desktop/mobile,
capability proof validation, legacy downgrade detection, incompatible-peer
rejection, signed manifest integrity/rollback and focused race tests passed.
- Remaining: anonymous metadata/calendar publication approval, Domain-create form
integration, entry-control release/GC, apply ACK/freshness and journal/outbox delivery.
- [x] Diary/blog initial built-ins — 2026-09-16.
`content.diary` and `content.blog` provide Domain-scoped, default-disabled
settings, Page UUID metadata, calendar/recent entries, category/month/mine
filters, and register/edit/unregister dialogs. Canonical content and revisions
stay in ordinary Pages. Metadata writes reserve SQLite's writer before live
membership, Path binding, grant/Locality and version checks; own-user Wiki
authority matches the semantic editor. Metadata journal commits atomically;
unregister/re-register generations prevent ABA replay. Private metadata is
not exposed anonymously; Page publication behavior is unchanged. Atomic
new-post composition, public metadata approval/feeds, comments and tDiary
import remain [explicit follow-ups](diary-blog-plugins.md).
Full Go suite PASS (Server 12.417 s), focused race PASS (Server 5.745 s,
Store 1.790 s), vet/JS syntax/diff checks PASS; combined config, public
navigation, governance and diary/blog Chromium PASS (9.332 s). PC/mobile
screenshots inspected under `/tmp/pageswiki-periodicals-review/`.
DB-only backups at
`/home/anya/.cache/pageswiki-backups/pre-periodicals-drFK6Ljf/` are mode 0600;
both quick_check results are `ok`. Backups use low-priority I/O.
Rebuilt image:
`sha256:9948aca99fa03eb43dda06a03ae59a680cad3d5b5284fd6c2217e09d69f75c22`.
Deployed to both nodes: local Host-routed health checks return `ok`, zero
restarts, served JS matches source. Both have all three additive tables and
zero enabled instances. Main anonymous root remains 200; diary/blog require
login (303) and unauthenticated metadata APIs return 401. Managed legacy-mode
diary also requires login. Existing main objects (1,448), publication
manifest (one) and approved entries (four) remain unchanged; no plugin was
enabled and no article was registered in production during verification.
- [x] Public children view controls now match the authenticated icon order and
sizing (`▦`, `☷`, `≡`), with localized tooltips/accessible labels and retained
active state. Desktop/mobile Chromium PASS (1.948 s), focused navigation tests
PASS (0.454 s), JS syntax and diff checks PASS. Rebuilt image:
`sha256:35b1fd0e0c291e42769b81dd50a53d237b94071431387c41b289d692a578e2b7`.
- [x] Anonymous navigation usability — 2026-09-16 23:19 JST.
Added public root/virtual-parent directory landings and read-only
`/v/browser/{path}`; separate Page/child-folder links, compact responsive
header and direct City exits. Public tree now supports all/per-folder
expand/collapse, name/Path filtering and arrow/Home/End navigation. Component
sorting keeps `/a/x` before `/a-b` for correct branch operations. Children
requests are capped at three concurrent fetches, cancellable and timed out,
with generation-safe retries and view-only session preference. Initial
directory/pagination links and macro fallback links work without JavaScript.
Full Go suite PASS (Server 12.387 s), vet/JS syntax/diff checks PASS;
focused race suite PASS (Server 7.287 s); broad Chromium suite PASS (19.837 s),
including anonymous navigation at 1440 px and 390 px. Screenshots inspected:
`/tmp/pageswiki-public-navigation-review/public-navigation-{1440,390}.png`.
Tests cover failure/retry, view switching, hierarchy prefix collisions,
pagination/exclusions, private-parent body suppression, bad credentials,
mutation denial and warm-cache revocation. See [contract](public-navigation.md).
Both nodes rebuilt/deployed with
`sha256:cf75c402c04cb185e1c7965480c35b352e2182c857af9367e7b3dfa672a68597`.
Both local Host-routed health endpoints return `ok`, zero restarts; managed
home returns 200. Main anonymous root/browser/tree/children/City return 200
(approximately 1–21 ms in local checks); protected autoplan remains 401.
Public directory headers retain private/no-store and inert CSP. Served JS/CSS
hashes match source on both nodes. No new schema migration; existing main
publication remains one manifest/four entries and its governance, topology,
binding, hash and head checks pass. No approvals or production content were
changed; no public TLS ingress change or verification is claimed.
- [x] Permission-aware public navigation — 2026-09-16 22:44 JST.
Ordinary approved Pages now offer asynchronous children, structural breadcrumbs,
read-only tree and filtered City Map; remove the public download control.
Navigation-free presentation remains a future share-URL concern. Cached data
uses SQLite mutation generations; authenticated membership/ACL decisions are
evaluated per request. City reload/retry discards previous authorized labels
before revalidation. See [navigation contract](public-navigation.md).
Full Go suite PASS (Server 9.335 s), vet, JS syntax and diff checks PASS;
broad Chromium suite PASS (16.670 s); focused navigation/ACL/publication race
tests PASS (Server 7.529 s, Store 14.706 s). Coverage includes warm-cache
publication withdrawal and group removal without data-cache invalidation.
DB-only SQLite backups in
`/home/anya/.cache/pageswiki-backups/pre-public-navigation-FMqnj5pu/` are 0600;
both quick_check results are `ok`.
Both nodes rebuilt/deployed with
`sha256:aade0a87dbdd0966c92908836dda57f5d5a3440028cb2181194104c8ede9f9ae`.
Host-routed local health checks return `ok`, both running with zero restarts;
managed home returns 200. Main anonymous tree/children/City HTML/map API return
200 (approximately 1–18 ms in the local smoke check), while autoplan remains
401. Tree response is private/no-store with inert CSP; main served JS hashes
match source. Additive navigation schema has 45 invalidation triggers on each
node. Existing main publication records remain one manifest/four entries;
managed records remain zero. No publication was activated or revoked by this
deployment. Public TLS ingress was not changed or certified by local checks.
- [x] Document hierarchical approval requirements and approver Inbox delivery.
[Approval design](publication-approval-inbox.md) defines inherited required
floors, immutable review subjects, live reviewer authorization, transactional
outbox/retry and recipient-private notifications. AP-1 through AP-6 remain
unchecked implementation work; this design does not enable a new workflow.
- [x] Named user/group locality read or read/write permissions, stable subject
identity resolution, superior-cap/authority-rank restriction preservation,
next-request membership checks, Object alias caps and SQLite namespace fences.
Explicit bounded anonymous current-revision approval/withdrawal now serves a
separate inert semantic Viewer and streaming raw-media path with safe OGP.
Per-scope publication generations prevent replaying pre-revocation consent.
See [scope, operational limitations and follow-ups](locality-access-publication.md).
Whole Go suite passes (Server 10.176 s, Store 4.560 s), focused race suite
passes (Server 6.206 s, Store 1.013 s), and approval/governance Chromium
checks pass (1.994 s); the broader browser suite passed (27.547 s).
Source-Domain restrictions also clamp exceptional foreign Object grants;
a regression verifies that these exceptions cannot bypass the new ACLs.
Vet, JS syntax and diff checks pass. SQLite backups (DB only) are under
`/home/anya/.cache/pageswiki-backups/pre-locality-access-lpnkGqwV/`, mode 0600;
both pass quick_check. Both existing nodes deployed as
`sha256:4a797ee34ef0c0fe0d48cea891a943393f0f722f07c192879f61b5dc3456ba9d`.
Host-routed local health checks return `ok`, both running with zero restarts.
Served governance JS hashes match the workspace on both listeners. All five
new access/publication tables exist and remain empty on both DBs: no production
restriction or public approval was created. Main anonymous home remains 303,
managed legacy home 200; anonymous access/publication administration requests
are denied (main 401, managed 403). Managed public TLS/vhost remains the
previously recorded infrastructure caveat; these are local listener checks.
- [x] Quartier/Spot co-owner appointments, Domain/local publication-cap drafts,
epoch/topology concurrency checks and in-transaction membership/authority
revalidation; local before/after audit and Japanese/English modal settings.
Includes bounded appointment-authorized member lookup. Full impact reports,
structural mutation fences and anonymous publication remain pending; existing
production visibility is unchanged. See [governance contract](locality-publication-ownership.md).
Verification: full Go suite (Server 8.584 s, Store 4.015 s), focused race
tests (Server 2.698 s, Store 1.015 s), combined City/governance/search/HTML
Chromium regressions (16.275 s), vet, JS syntax and diff checks pass.
Pre-migration SQLite backups (DB only, not a complete DR package) are under
`/home/anya/.cache/pageswiki-backups/pre-governance-aNwngqHe/`, mode 0600.
Both backups pass `PRAGMA quick_check`. Both existing app nodes deployed as
`sha256:dc6960ba1b01800b08351f660d20848dcca0e0f7f382fe18e362d93f7171d147`.
Local Host-routed health checks return `ok`, zero restarts; all four additive
governance tables exist on both DBs, with no owners/policies automatically
inserted. Served governance JS hashes match the workspace on both nodes.
Anonymous governance requests are denied (main 401, managed 403); main home
still redirects to login (303). No production owner appointment or public
policy change was made as a smoke test. Existing managed public TLS caveat
remains; these are local listener/Host checks, not a TLS infrastructure fix.
- [x] P0 inert HTML display boundary across semantic/home/profile/object/history/
preview/print and HTML/Markdown Editor previews; canonical content unchanged.
Application nonce CSP, forged macro-hook stripping, escaped failure fallback,
bounded/cancellable City macro reads, and ACL-checked sandboxed diagram cache.
See [precise policy and compatibility](html-projection-trust.md). Owner/public
APIs and new anonymous access remain disabled/pending. Final full Go suite
passes (Server 7.866 s), focused race tests pass (Server 4.247 s, Store
1.057 s), and final HTML/PDF/archive/editor/bookmark Chromium tests pass
(14.006 s). Broader City/search/login Chromium checks also passed (27.590 s).
`go vet`, editor JS syntax and diff checks pass. Read-only compatibility
sampling was limited to 500 HTML revisions; it was not a complete Path audit.
Deployed both existing nodes as
`sha256:41cd97c7705b8be6b1bf763aee7678c5d510878d5ec6d78aa3b3792a7eb32517`.
Both local Host-routed `/health` endpoints return `ok`, zero restarts; managed
home returns 200 with nonce CSP, nosniff, private/no-store and
`X-PagesWiki-HTML-Policy: inert-v1`. Main anonymous home still redirects to
login (303). Both served Editor scripts match workspace SHA-256. No schema
migration, production document rewrite, visibility change or TLS change.
Managed public TLS/vhost caveat from the earlier social-card check remains
outside this deployment; these checks do not claim public HTTPS there works.
- [x] OGP/X cards for existing public semantic Page/home/City HTML, bounded
canonical text extraction, configured-host canonical/image URLs, original
image-document cards and an application-owned cached PNG fallback. No crawler
auth bypass, external image fetch, schema migration or visibility change.
Private/enforcing HTML suppresses metadata and adds noindex. See
[social card policy](social-link-cards.md). Full Go suite (Server 6.818 s),
social race tests (2.434 s), City/search Chromium checks (3.846 s), vet and
diff checks pass. No claim of actual X post/card display; no post was sent.
Deployed both nodes as
`sha256:a16fa6cbe8a3a6b5141d7d29de0e6faef67989285a9983b2ffa306d4e016b75c`;
both health endpoints return `ok`, zero restarts. Managed-host anonymous home
includes HTTPS OGP/card URLs, image HEAD returns 200/image/png (7,327 bytes),
main `pages.anya.jp` still redirects anonymous crawlers (303). The common
image is also reachable through public HTTPS; its 1200×630 output was visually
inspected. No private production Page was made public for this test.
External caveat: `https://wiki.extpages.anya.jp/` and its image fail TLS with
`unrecognized name`; managed-host checks above used its local app listener
with the configured Host. Public HTTPS image success was on `pages.anya.jp`.
Fix the managed FQDN's TLS/vhost before expecting external cards there.
- [x] City named-reference follow-up: qualified Street URLs, shared links,
explicit UUID locality search, ancestor-aware lightweight details and literal
Page links in both the map and inspector. No schema/data migration required.
Whole-map loading is also deferred out of simple City breadcrumb macros.
Verification: full Go suite, City/search browser regressions (including
repeated Street names and three initial-focus levels), `go vet` and JS syntax
checks pass. City/search race tests also pass (Store 35.000 s, Server
7.391 s); the combined Chromium suite passes in 13.166 s. The HTML trust gate
and broader CITY-A–D work remain open.
Deployment: both existing app nodes rebuilt/recreated as
`sha256:8e53fec5c485ed5763bf44705cfdf4071d04f2b8932dca038148eedda26f4c42`.
Both health endpoints return `ok`, zero restarts; main unauthenticated City
request redirects (303), managed-host search returns 200 under its existing
policy. Served City map/estate scripts match workspace SHA-256 hashes.
- [x] OIDC issuer JWKS signatures, claim validation, bounded discovery/key cache;
one-use browser state and collision-safe external account linking.
- [x] Bounded SMTP delivery, safe headers/mailboxes, live account checks.
- [x] Campus-admin inheritance revocation, provenance and local-right preservation.
- [x] Recursive Path mutations: transactional authorized snapshots and literal prefixes.
- [x] Browser mutation CSRF protection and explicit credential precedence/logout;
browser/API purpose prefixes and atomic active-session checks.
- [x] Object authority scope and atomic creation provenance; safe all-alias purge.
- [x] Signed manifest allocation/application/checkpoint atomicity and authority guards.
- [x] City map/detail/Page list read filtering and private response caching policy.
- [x] Batch/request-scoped read authorization to reduce listing query amplification.
- [x] PDF/archive metadata scheduler projections with persistent bounded cache.
- [x] City generator Worker and directional keyboard navigation.
- [x] Search results: compact overview, full Page Path, matching-text excerpts and
safe keyword highlighting; retain list/detail/thumbnail integration and read ACLs.
- [x] Object/Revision metadata pagination and localized history navigation.
- [x] Literal URL encoding in children list/detail/icon projections.
- [x] City one-connection-safe read snapshot and literal boundary lookup/health.
- [x] Atomic bounded zombie GC and Domain-provenance-scoped HTTP administration.
- [x] Integrated Go/browser tests, rebuild, and both instance health checks.
Update this list only after the corresponding implementation and verification.
The broad phase checkboxes stay open when only a bounded slice has landed.
Focused implementations, constraints and regressions are linked from
[Implementation status](implementation-status.md#confirmed-corrections-2026-09-14).
## Verification and deployment
Completed 2026-09-14 01:43 JST. All source changes were frozen before rebuilding;
later edits only recorded the final outcomes in design documents.
- Final `GOMAXPROCS=2 GOCACHE=/tmp/pageswiki-go-cache go test ./... -count=1`:
PASS for all packages (server 5.947 s, store 3.105 s).
- Targeted server/store `-race` covering authentication, inheritance,
recursive/Object integrity, federation, GC, City and metadata projections:
PASS (server 21.774 s, store 38.202 s). Independent focused race runs also
covered search, pagination and the final deterministic GC regression fixture.
- Opt-in Chromium: 13 suites PASS (48.544 s), covering real HttpOnly-cookie
login/logout, City normal/popup/mobile and Worker/navigation, search in all
three modes, PDF/archive/comic metadata, settings, execution monitor,
bookmark/Vim settings UI and editor/home. This does not validate the paused
vim.wasm runtime. Artifacts: `/tmp/pageswiki-hardening-final`.
- `go vet ./...` and `git diff --check`: PASS.
- Before schema migration, online SQLite backups of both nodes completed with
`PRAGMA quick_check` = `ok`. Directory:
`/home/anya/.cache/pageswiki-backups/pre-hardening-20260914-1wH8jcKm/`.
`app.sqlite` and `app2.sqlite` are mode `0600`; their containing directory is
private. These are DB snapshots, not complete Document-store/key DR backups.
- `docker compose build app` and `docker compose up -d --no-deps app app2`:
PASS. Both containers run image
`sha256:dc0ac3305c6a6abb42d84e56c8291cabc9c582a421f4ce91ca4276b123735ad2`,
with no restart loop. Both local `/health` endpoints return `ok`.
- Main-instance search CSS and City Worker client hashes match the working
files; managed-instance search CSS matches too when using its configured Host.
`https://pages.anya.jp/` and the protected main search route return the
expected unauthenticated `303`; the managed Domain search route returns
`200` under its existing read configuration. A foreign-Origin unsafe request
is rejected with `403`. No production account credentials were used.
Browser behavior tests used isolated fixture databases, not production content.
Live external OIDC/SMTP provider credentials and production multi-user flows
were not exercised; protocol, denial and concurrency coverage used test fixtures.
### Search timeout follow-up — 2026-09-14 03:47 JST
The user reported a search timeout after the initial deployment. Read-only
production-data investigation found a Path-first repeated FTS scan and
unbounded snippet input work, neither represented by the original small fixtures.
Corrected the join order, rowid excerpt lookup, per-document/total snippet input
budgets and optional 400 ms enrichment deadline. Results survive snippet-only
timeouts; genuine search failures now have localized, non-leaking retry UI.
See [evidence and remaining search limits](search-results.md#timeout-regression-and-correction-2026-09-14).
- Full Go suite PASS (server 6.869 s, store 3.511 s); search `-race` PASS
(server 2.967 s, store 8.063 s); Chromium search PASS (0.740 s);
`go vet ./...` and `git diff --check` PASS.
- Added query-plan assertions, a 600-Page/1,200-Revision regression, Unicode
byte-budget/alias tests, deadline/error tests and large-body UI coverage.
- Read-only diagnostics against the existing main DB passed twice, with
representative search processing times around 72–506 ms. No production
account credentials or Page content were output or changed.
- Rebuilt/deployed both app nodes with image
`sha256:0f10da866a03167da7811ddc88f66d6a65bd27aae17557c824a9f7b5071b88a8`.
Both `/health` endpoints return `ok`, no restart loop, search CSS matches
source on both configured hosts. No schema/index migration was needed.
### City-first search and filters — 2026-09-14 04:05 JST
Added permission-filtered, metadata-only Quartier/Street/Spot results above
Pages. Added a compact options disclosure for MIME/suffix categories, a single
extension, and creation/update calendar-date ranges. Options persist in the
GET URL and retry link. File-specific filters exclude City metadata; date
filters apply to both. City/Page queries share the existing deadline and do
not load the full City graph. See [search contracts](search-results.md#city-first-results-and-search-options).
- Full Go suite PASS (server 6.746 s, store 3.470 s); combined search/City
`-race` PASS (server 4.288 s, store 10.257 s). Added filtered-query plan
coverage also passed in the final Store search race run (18.373 s).
- Chromium desktop/mobile (1440/390 px) PASS, including real City results,
safe links, match highlights, preserved filters, all Page view modes and
separation from file multi-selection. Final run: 1.173 s. Screenshots:
`/tmp/pageswiki-search-city-final/search-results-desktop.png` and
`search-results-mobile.png`. `go vet ./...` and `git diff --check` PASS.
- Read-only main-DB verification: representative keyword search 79–515 ms,
filter-only cases 1–6 ms, City metadata 2 ms. These are Store timings, not
authenticated production HTTP measurements. No schema migration is needed.
- Both app nodes rebuilt/deployed with image
`sha256:1f6d64c354e940c0941db9914a836f47e7285ac962a9c68f9b6cebcddd2e0dc3`.
Both `/health` endpoints return `ok`, zero restarts, source CSS hashes match
each configured host. Protected public search returns the expected `303`
without credentials; managed-node filter-only search returns `200` under
its existing read configuration.
## Deliberate high-risk deferrals
- Executable authored-HTML compatibility is not supported. Normal HTML now uses
the inert projection boundary; any future executable mode requires separate
origin/capability approval and isolation tests. Public locality ACLs and owner
governance still require transaction/cache revocation gates. See
[policy and acceptance tests](html-projection-trust.md).
- HA/LB writable metadata, controller DR promotion and distributed job leases:
need a selected replication strategy, fencing, key custody and fault drills.
- Untrusted third-party code/plugin execution and native application launch:
need isolated runtime, signature/capability lifecycle and a separate helper
trust model; existing hosted editor integrations remain supported.
- Production S3/SSHFS/WebDAV/MWDB/Karton/SNMP/LDAP integrations: implement only
after endpoint/credential policy and test services are available. No fabricated
live integration claims or unrequested credential/infra provisioning.
- Broad notifications/inbox, comments, diary/tDiary import, rankings and external
search: retain the existing detailed contracts; gate on transactional activity
provenance, privacy/retention and authorization. Small prerequisites may land
first, without claiming those product features complete.
- vim.wasm runtime remains explicitly on hold from the earlier user instruction.
These are not removed from the roadmap. Lower-risk outstanding items that do not
fit this batch remain unchecked, with the next sequence recorded at handoff.
## Next implementation sequence
1. Complete locality Page/alias/dependency impact reports and structural mutation
fencing on the implemented owner/draft-policy foundation. Require fresh
activation consent and endpoint/cache revocation coverage before anonymous
access; never silently activate saved drafts.
2. Complete mutation authority/version fencing and local/external account
ownership lifecycle, then remaining endpoint/adapter denial audits.
3. Add shallow, paginated City projections and transactional mutation outbox /
reconciliation provenance; retain manual curation when deriving from URLs.
4. Replace remaining full directory aggregates and historical/raw-HTML FTS work
with current-only bounded projections; add cancellation-aware streaming or
immutable-hash clone operations for large binary changes.
5. Resume activity/notification and trusted system-extension product slices
after those authority and event-provenance prerequisites. Keep HA/DR and
external-service provisioning behind their separately documented decisions.
+146
View File
@@ -0,0 +1,146 @@
# Home navigation and hosted Vim follow-up
## Application assets and editor routes
Templates load CSS and JavaScript from `/static/`. The legacy
`/o/path:/system/static/` namespace remains a read-only compatibility alias to
the confined static file server. It is not a UUID/Object address and must not
be sent through document authorization. Other `/o/` addresses remain protected.
`/e/docs` and `/e/-/docs` both edit `/docs`; `/e/`, `/e/-`, and `/e/-/`
edit `/`. The authorization target and editor use the same path decoder.
Database resolution errors must not be mistaken for a missing page.
## Bookmark sections
The Domain-scoped `home_bookmarks` JSON array stays backward compatible:
```json
[
{"kind":"section","label":"Reference","href":"","children":false},
{"kind":"url","label":"Example","href":"https://example.com/"},
{"kind":"section","label":"Documents","href":"/docs","children":true}
]
```
A section starts a card and owns subsequent links until the next section.
Legacy links before any section form a default card. `children=true` replaces
that section's displayed links with the immediate children of its parent Path;
manually configured links remain stored for when the toggle is turned off.
Virtual folders are included, but `/u`, `/_`, and `/-` are excluded at the root.
Management is available through a small settings icon on every home layout to
Domain/Campus admins. A native modal dialog provides focus containment, Escape
and close-button dismissal, while retaining unsaved edits if closed. The same
section-card editor is used at `/-/sys/config?panel=bookmarks`. Section moves
and deletion operate on the entire group; links can be moved to another
section using a selector. Page content is never deleted by bookmark deletion.
Saves use the existing server validation and request JSON acknowledgement;
errors remain in the form instead of navigating away. On success the home
reloads its cards. A navigation warning protects unsaved edits. Classic and directory layouts show cards; the
search-only layout retains its search focus while allowing management.
Limits: 64 rows total, including at most 16 section rows. Labels and URLs are
validated server-side; invalid submissions leave previous settings untouched.
Path URLs escape literal percent signs, fragments, spaces and Unicode.
`GET /v/bookmarks?section=<array-index>&after=<last-child-name>` loads children
as JSON. It resolves the section within the active Domain, checks the parent
and each child against current read permissions, and returns at most 80 scanned
children per request with a continuation cursor. No revision bodies, metadata
stats, thumbnails or full-Domain listing are loaded. Queries use the Path
prefix index and request cancellation. Browser loading is lazy and limited to
two concurrent requests. Responses are `no-store`, avoiding stale permission
results. Empty filtered pages may still contain a continuation cursor.
Follow-up: batch authorization and materialized immediate-child indexes for
extremely large subtrees; optimistic concurrency for multiple administrators
editing the same configuration (currently last successful save wins).
## vim.wasm configuration and plugins
The pinned runtime writes injected files using `wx+`: an existing bundled
`/.vim/vimrc` is skipped, despite the package README suggesting overwrite.
Use a new `/pageswiki.vimrc` MEMFS file and explicit `-u /pageswiki.vimrc`.
This is verified inside the real Wasm binary, not merely by HTTP success.
The Gateway image bundles the existing licensed Hack Nerd Font locally.
`document.fonts.load('16px PagesWikiHack')` completes before startup so canvas
cell widths use the final font. `guifont=PagesWikiHack:h16` controls actual Vim
rendering; CSS alone does not. Font, Worker and Wasm retain same-origin isolation.
`assets/vimwasm/app/vimrc` sets line numbers, cursor line, status line, search,
indentation and dark colors. `pageswiki.vim` is a bundled pure-Vimscript plugin
in `/.vim/plugin`, with an explicit runtimepath. Available operations:
- `:Files` / Space+f: `:find` with Tab completion beneath `/work`.
- Space+b: buffer listing and selection.
- `[b` / `]b`: previous/next buffer; `:next` still traverses arguments.
- Space+w: write; Space+/: clear search highlight.
The existing BufWritePost export and scoped Gateway write-back remain in use.
The base settings are image-managed. Domain administrators can customize them
at `/-/sys/config?panel=adapter-vim.wasm`, separately from connection settings.
### Domain customization contract
`POST /-/sys/config/vim` stores one `vim_wasm_settings` JSON config value per
Domain: `enabled`, `font_size` (10–32), `vimrc`, `colorscheme`, `color_name`.
The settings panel uploads UTF-8 files into editable text fields, supports
download, custom-colorscheme removal, and reset to defaults. Each script is
limited to 64 KiB; NUL bytes, invalid UTF-8 and path-bearing filenames are
rejected server-side. One custom colorscheme is managed initially; uploading
another replaces that slot. Nothing is written into the host filesystem.
Only active builtin Domain/Campus administrators can save; readonly accounts
cannot mutate executable configuration even if they retain group membership. A supplied Origin must
match the request Host. Vimscript is executable trusted configuration and may
invoke browser integration features; it is not a safe format for untrusted
uploads. This is explicitly disclosed in the UI. No server shell, terminal,
package manager or arbitrary process execution is exposed.
An authorized `vim.wasm` workspace response includes the session Domain's
`vim_settings`. The Gateway retains that snapshot in its server-side session
and supplies it with `GET /vim/api/session` (`no-store`). Other adapter types
do not receive these settings. Changes apply on a newly opened session.
MEMFS initialization order: bundled defaults, configured font size, source
`/pageswiki-user.vimrc`, then a fixed-path custom colorscheme under
`/pageswiki-config/colors/pageswiki_custom.vim`. A conventional uploaded name
matching `[A-Za-z0-9_-]+.vim` is also registered as a local alias before the
user vimrc is sourced, so `colorscheme uploaded` works for `uploaded.vim`.
Other uploaded filenames remain display metadata; no uploaded name is inserted
into a command. Disabled customization
retains source text but does not execute it. `?safe=1` on the Vim frontend URL
skips all Domain customizations, including the font size, so a broken startup
script cannot prevent recovery through the defaults and settings panel.
Follow-up: versioned per-user settings, multiple named scheme slots, and an
isolated test-startup window. A restricted terminal is not needed for the
current configuration workflow. Any future terminal bridge needs a separate
capability, runtime sandbox, resource limits and explicit authority design.
Third-party plugin policy: vendor pinned, licensed pure-Vimscript files into
MEMFS and test against this old pinned Vim feature set. Candidate classes are
surround/text-object/comment helpers without native or network dependencies;
no unreviewed third-party plugin is added by this change. Runtime vim-plug
installation is unsupported. Vendoring `fzf.vim` alone is insufficient because
fzf requires a native executable; shell/system()-dependent plugins belong in
code-server or need a separately designed Wasm/JavaScript bridge.
## Verification
`go test ./...` includes asset routing, matching editor/authorization paths,
section persistence, invalid input, admin restrictions and child access tests.
Opt-in browser tests:
```sh
PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run 'TestEditorHomeChromiumSmoke|TestConfigChromiumSmoke|TestVimWasmChromiumSmoke|TestBookmarkAndVimSettingsChromium' -count=1
```
The Vim test uses CDP real-time waiting (virtual time can finish before Worker
compilation), two isolated files and a fake save endpoint. It asserts the actual
guifont, loaded `:Files` command, argument count and absence of startup errors.
It also edits a buffer with `:write` and verifies that BufWritePost exports the
changed bytes to the fake Gateway save endpoint. Both custom settings and safe
mode are exercised. UI tests open and close the settings dialog, save a
section with automatic children, and upload/save vimrc and colorscheme files.
+317
View File
@@ -0,0 +1,317 @@
# HTML projection trust boundary
Audited and remediated: 2026-09-14; controlled external-resource extension:
2026-09-23. Status: **normal HTML projections use `controlled-v2`**. Authored
active HTML remains denied by default. A Domain administrator may separately
approve an exact external resource URL; approved JavaScript is intentionally
executable and is therefore a high-trust Domain configuration action.
## Implemented contract — controlled-v2
`internal/server/html_projection.go` applies a parser-based allowlist using
[bluemonday](https://github.com/microcosm-cc/bluemonday), pinned to v1.0.27. The
sequence is bounded token preflight → authored allowlist → tree normalization
and authorized macro expansion → diagram references → final allowlist. This
changes display projections only, not saved Documents, hashes or Revisions.
- All known authored-HTML surfaces share this boundary: semantic Viewer,
configured home, profile Wiki, object UUID, historical Revision, Preview,
print, and HTML/Markdown editor preview. Object viewing checks adapter MIME
kind; non-HTML is escaped text or a download link, never blind HTML.
- Formatting, tables, code, internal/external links and local passive images
are supported. Author scripts, event attributes, forms, iframes, SVG/MathML,
styles, arbitrary classes and `data-*` hooks are removed. This is intentional
compatibility tightening, not a source migration or an executable trust flag.
- By default images must resolve to local `/v/raw/`, `/_/obj/`, `/static/`, or
`/o/path:/system/static/` resources after path normalization. External images,
relative semantic URLs, data images and arbitrary authenticated GET targets
are not loaded by authored markup. Use immutable asset/raw references.
- The Domain setting “Approved external resources” is the only exception.
External images require an exact normalized HTTPS URL match. External CSS
and JavaScript require both an exact HTTPS URL and pinned SHA-256 SRI. The
server discards authored integrity/crossorigin attributes and emits canonical
`integrity` and `crossorigin=anonymous` attributes from configuration.
Approval entries are converted to unpredictable text placeholders before the
authored and generated allowlists, then restored as server-authored tags;
macro output therefore cannot forge an approval. CSP is derived from the same
list: image/style origins and JavaScript content hashes are added while
`connect-src` remains same-origin. Revocation takes effect on the next render.
Wildcards, HTTP, credentials, fragments, inline script/style and event
attributes remain unsupported. Because approved JavaScript can invoke
same-origin APIs as the viewer, only immutable audited code should be added.
- Authored IDs and fragment targets are SHA-256-namespaced to avoid application
DOM collisions. Only code-language classes survive the authored pass.
- Only text-node macros expand, not macros in attributes, links or code.
Application-owned children hooks cannot be forged by authored `data-*`.
Each macro is dispatched once; lookup failures remain escaped authored text,
including entity-decoded tags and nested-macro-looking strings.
Existing read filtering is retained; City reads inherit request cancellation
and use bounded Store projections. Macro output is not cached across readers.
- Input is at most 1 MiB; token/tree budgets are 16,384 with depth 128; output
is at most 4 MiB before final sanitization; at most 32 macro invocations.
Preflight is deliberately conservative for deeply/unclosed malformed HTML.
Cooperative request/DB work has a two-second deadline. These are bounds, not
hard CPU isolation of the in-process parser. Failure shows a localized warning
and at most 64 KiB of escaped source, never original active HTML.
- `/_/api/v1/render/markdown` accepts optional `html` only with `projection:true`.
Display results are private/no-store. Canonical Markdown-to-HTML conversion
remains separate and preserves authoring semantics; it must not be displayed
without projection. Editor preview requests debounce/abort obsolete work and
fail to escaped text. Saving does not save the sanitized preview.
- Normal display/editor templates use per-response CSP nonces for application
scripts and prohibit authored inline event handlers. Nonces are inserted into
trusted template source **before** request data, never rendered body strings.
Same-origin application frames/resources remain available; document styles
are removed while application/theme styles remain enabled. Config and other
non-document screens are not claimed to have this CSP yet.
- Diagram SVG responses, including cache hits, have sandbox CSP and nosniff.
GET cache use requires current Domain/Path read authority and a live bounded
source reference (128 entries, 32 KiB/source, 30-minute lifetime). These
references are keyed by policy version, Domain, Path and source; responses
are private/no-store so browser caches do not bypass fresh checks. Reopening
the Viewer registers references after restart/eviction. Renderer requests
inherit cancellation; source/cache/output reads are size-bounded. Durable
diagram scheduling, disk quotas, atomic artifact publication and hard decoder
isolation remain follow-up work; foreground diagram GETs are not eliminated.
- There is no grandfathering of old active HTML and no document-level trusted
executable mode. The explicit Domain approval list above is the only active
external-resource exception.
Registered application/plugin frames are separate trust contracts. Anonymous
locality ACLs, ownership appointments, alias/move fences and public cache
revocation must land before enabling new public access.
Verification: `html_projection_test.go`, `html_projection_browser_test.go`, and
`diagram_projection_security_test.go` cover inert attack corpora, resource limits,
cancelled requests, unchanged stored content, cache authority/revocation and CSP.
Real Chromium loads nine display/editor surfaces as an administrator after a
path-scoped writer saves a hostile test document through the real save API.
Authored execution and privileged sentinel requests must stay absent; parser-
inserted non-nonced scripts/events are also blocked by CSP. Existing PDF/archive/
comic, metadata, bookmark and editor browser regressions remain required.
Read-only compatibility sampling of the main DB's latest 500 HTML **revisions**
(not a complete current-Path inventory) found no script/event/iframe/SVG markers
in their first 128 KiB, one style-bearing revision, and no body over 1 MiB.
This limited marker count is not a sanitizer/security proof or a guarantee that
no existing document needs layout changes. No production document was rewritten.
The following sections preserve the original diagnostic and design rationale;
their unsafe behavior describes the **pre-remediation** implementation.
## Finding and release gate
Before remediation, saved HTML executed JavaScript in the Pages Wiki application origin
when a reader opens its semantic Viewer. Document write permission therefore
implicitly grants the ability to execute code as a later reader, including a
reader with stronger permissions. Authentication, path ACLs, and CSRF checks do
not make authored HTML safe after it is inserted into the authenticated page.
HttpOnly cookies cannot be read directly, but same-origin authored code can
issue authenticated requests and read accessible responses or the page DOM.
**Before enabling or broadening shared links, comments, anonymous/public
viewing, or untrusted-author publication, this boundary must be closed and its
browser regression suite must pass.** This is also an existing risk in private
Domains with authors and readers of different privilege levels; it is not
limited to future public features. Do not describe the pre-remediation Viewer as an
isolated HTML viewer, or treat an HTML MIME classification as a trust decision.
## Observed entry paths (before remediation)
The central semantic path is:
`Revision.Body → expandMacrosForRequest → renderDiagramsInHTML → template.HTML → parent page DOM`
The macro and diagram helpers replace recognized constructs; they are not HTML
sanitizers and preserve unrelated scripts and event attributes. Go's
`template.HTML` deliberately bypasses normal template escaping.
| Entry / projection | Current implementation and insertion |
| --- | --- |
| `/{semantic-path}` | `internal/server/semantic_handlers.go`, `handleSemanticRoute`: HTML-kind `Revision.Body` is expanded and cast to `template.HTML`; `templates/pages/page.gohtml` inserts `.RenderedHTML` directly into `.page-html`. |
| `/` with a configured HTML home Path | `internal/server/handlers.go`, `handleHome`: the saved home body is macro-expanded and inserted through `page.gohtml`. |
| `/o/uuid:{object-uuid}` | `internal/server/object_uri_handlers.go`, `handleObjectView`: casts `latest.Body` directly to `template.HTML`, without even the MIME/adapter-kind guard; `object_view.gohtml` inserts it into the parent document. |
| `/r/view/{revision-uuid}` | `internal/server/revision_routes.go`, `handleRevisionView`: HTML-kind historical body is cast directly and inserted by `revision_view.gohtml`. |
| `/v/preview/{path}` | `internal/server/preview_handler.go`, `handlePreview` / `renderPreviewDocument`: HTML-kind body is expanded and inserted by `preview.gohtml`. |
| `/_/view/print/{path:…\|uuid:…\|rev:…}` | `internal/server/print_handler.go`, `handlePrint`: HTML body is expanded and inserted by `print.gohtml`. |
| `/u/{username}` | `internal/server/profile_handler.go`, `handleUserProfile`: the associated user Wiki HTML is expanded and inserted by `profile.gohtml`; child Wiki pages use the semantic handler. |
| `/e/{path}` live Preview | `static/js/editor.js`: HTML source and Markdown projection responses are assigned to `preview.innerHTML`. This is another active-markup sink to cover; script-tag behavior under `innerHTML` differs from initial document parsing, but event attributes and other active content must not be considered safe. |
The first row was verified in a real browser. The remaining rows were traced in
source and require endpoint-specific browser coverage during remediation. This
is an inventory of known sinks, not proof that no additional projection exists.
### Protections that do not cover these paths
Raw HTML download/attachment handling in `internal/server/raw_view.go`, the CSP
sandbox on raw SVG, and the sandboxed EML HTML frame are separate response
paths. They do not constrain saved HTML inserted into the normal Viewer.
The audited semantic response had no `Content-Security-Policy` header and its
authored content was not in a sandboxed iframe. `nosniff` or a correct
`text/html` Content-Type would not remove executable content.
## Local verification
A scratch Go test, injected with `go test -overlay` rather than added to the
repository, created a temporary migrated DB and temporary Document root. It
saved a test-only HTML Revision, bound `/audit/sentinel`, and served the real
semantic handler and templates through a localhost `httptest.Server`. A test
owner session supplied request authorization; no external instance was used.
Headless Chromium loaded that local page.
The payload contained only a paragraph, an inline script setting
`document.documentElement.dataset.htmlScriptAudit`, and an invalid `data:` image
whose `onerror` set `dataset.htmlEventAudit`. Both sentinel values became
`executed` in the parent DOM. The HTTP response still contained the original
inline script and its CSP header was empty. There was no data extraction,
credential access, or application mutation from the payload.
This diagnostic confirmed the current unsafe behavior; it is not a permanent
test that expects the vulnerability to remain. Remediation must invert those
expectations into denial tests.
## Mismatch with existing design
- [Architecture](arch.md) distinguishes immutable Document content from Revision
identity. Canonical HTML support does not itself authorize executable
JavaScript, and the reviewed architecture does not define all authors as
trusted application-script authors.
- [Projection adapters](projection-adapters.md), “Security and Failure Rules,”
says stored HTML and SVG retain their existing isolation rules. In practice
the raw/SVG isolation is not shared by semantic HTML projections. That wording
was insufficient to establish the missing boundary. That document now
records the implemented common projection boundary and its limits.
- [Platform extension architecture](platform-extension-architecture.md)
explicitly says document content may request a widget provider/resource but
may not supply executable JavaScript; providers use a sandboxed frame or a
sanitized server projection. Direct authored HTML execution bypasses that
intended separation.
- The Preview adapter-kind check prevents treating every binary/text file as
HTML, but it does not make a legitimately classified HTML body trusted.
## Policy rationale: immutable source, controlled projection
### Normal HTML is inert
Keep canonical Document bytes, hashes, Revision IDs, history, and authoring
round trips unchanged. Enforce safety when producing a display projection,
using a parser-based allowlist rather than regular-expression replacements.
The normal mode must not allow authored scripts, inline event handlers,
executable URLs, active embedded documents, or attributes that create a second
execution context. Define URL schemes, relative URL resolution, allowed markup,
CSS/layout limits, and external resource/privacy behavior explicitly. SVG,
MathML, `srcdoc`, forms, CSS URLs, and DOM-clobbering attributes need explicit
decisions, not implicit passthrough.
Introduce one projection boundary shared by Viewer, home, profile, historical
Revision, preview, print, and client-side editor preview. Object-UUID viewing
must also use the MIME/adapter registry rather than blindly casting a body.
If projection parsing fails or exceeds resource bounds, fail safely to escaped
source/download; never fall back to unsanitized HTML.
Distinguish authored nodes from server-generated macro/widget output. Parse
recognized macro requests into structured inputs, authorize their data access,
and produce escaped, typed output through trusted renderer contracts. A string
that resembles generated markup is not proof of trust. Avoid sanitizing only
before an expansion that can reintroduce authored unsafe attributes, or only
after expansion without accounting for required application-owned controls.
No general template call site should be able to turn arbitrary `Revision.Body`
into trusted markup by convention alone.
Editor authoring mode continues to preserve source, while its visual preview
uses the same safe projection policy. Do not conflate a safe display result
with a replacement for the canonical body when saving.
### Explicit trusted HTML is isolated
If executable HTML compatibility is genuinely required, make it a separate,
administrator-granted capability and an explicit Domain policy, not an implied
consequence of page write permission. Bind approval to the actual approved
content/revision or to a clearly defined trusted publishing workflow: granting
trust to a mutable Path must not let any later lower-privilege editor inherit
script execution. Define revocation, audit records, and visible mode indicators.
Executable content must not run with application-origin authority. Consider a
dedicated uncredentialed origin or an opaque-origin sandbox, with the minimal
permissions needed for that use case. Never combine same-origin document
content with permissive `allow-scripts allow-same-origin` and call it isolation.
Do not forward application cookies, bearer tokens, unrestricted save callbacks,
or privileged data into that context. Any necessary `postMessage` integration
must be narrowly typed, sender-checked, capability-scoped, and bounded; an
opaque-origin sender requires validating the known frame/window and a dedicated
channel rather than trusting the string `null` as an origin.
Existing application/plugin scripts remain a separate administrator-controlled
surface. Registered widget/plugin frames must not become an escape hatch for
arbitrary page-authored code or inherited reader capabilities. Shared/public
projections and comments must always use the safe policy unless a separately
reviewed, isolated publication contract explicitly permits more.
### Defense in depth and scaling
Adopt an application CSP compatible with approved application scripts, using
nonces/hashes or external script assets rather than unrestricted inline script
execution. CSP is defense in depth, not a substitute for safe markup and
isolation. Frame responses need their own policy; tightening only the parent
page does not fully define each child document's privileges.
Bound input size, parse depth/nodes, output size, CPU time, and any external
resource work. Cache content-only safe projections by immutable Document hash,
renderer version, and safety-policy version. Keep ACL-dependent macro output
separate or key/revalidate it with Domain, principal/grants, and request context;
never reuse a privileged projection as an anonymous/shared response. Cache and
preview artifacts generated under an older unsafe policy need invalidation.
## Compatibility impact and staged implementation
Existing pages may rely on inline scripts, handlers, style blocks, custom
attributes, embedded frames, forms, or SVG. Blanket filtering can break those
pages, diagrams, child-list controls, and editor previews. A restrictive CSP
also affects inline application scripts. The implementation above deliberately
separates these template-owned scripts from authored HTML; original source stays
available for editing/download if custom layout needs adjustment.
1. Approve the default allowlist, external-resource policy, and whether a
trusted executable mode is needed at all; record explicit ownership.
2. Inventory active constructs with a read-only diagnostic and report affected
Paths only to authorized administrators. Do not rewrite stored content.
3. Build the common projection boundary and server/client regression fixtures;
preserve supported macro, diagram, print, and editor behavior deliberately.
4. Integrate every known route, safe error fallbacks, policy-versioned caches,
CSP, and any separately reviewed isolated mode. Do not grandfather all old
HTML as trusted or infer trust from MIME, filename, creation time, or author
display name.
5. Verify upgrades and rollback without changing canonical bytes. Only then
remove the P0 gate for public sharing, comments, and anonymous expansion.
## Required tests and acceptance criteria
- Browser denial fixtures for parser-inserted scripts, event attributes,
executable URL variants, SVG/MathML active content, iframe/srcdoc, malformed
markup, DOM clobbering, and CSS/resource-policy violations. Use harmless DOM
sentinels and local test endpoints, not credential-exfiltration payloads.
- Apply the same corpus to semantic Path, configured home, object UUID,
historical Revision, user Wiki, preview, print, and both HTML/Markdown editor
previews. Test direct navigation, client-side replacement, and restored
revisions, not just the first render of new content.
- Cross-account fixtures: a lower-privilege author cannot execute in a reader's
page or issue reader-authorized mutations. Anonymous/shared viewers and
comments cannot activate markup or receive private macro results.
- Canonical Document bytes, SHA-256, Revision IDs, downloads, and authoring
round trips remain unchanged. Non-HTML bodies are never interpreted as HTML
by the object-UUID route. Unknown formats and parser failures stay inert.
- Supported formatting, links, images, children macros, diagrams, code blocks,
accessibility, themes, and print layouts still work. Template-owned controls
are not confused with forged authored markup.
- If trusted mode is implemented, verify origin isolation, cookie/token
exclusion, navigation/form/download permissions, message validation,
approval-on-edit behavior, revocation, and public-projection restrictions.
- Test CSP headers and violation behavior, resource bounds, cancellation,
oversized/deep input, cache policy-version changes, ACL revocation, and no
privileged-to-public cache reuse. A single endpoint-only sanitizer test is
insufficient to close this gate.
Acceptance requires inactive authored markup in every normal projection, an
explicitly reviewed policy for any executable mode, preserved canonical
content, and passing endpoint/browser integration tests. The normal projection
slice meets this boundary with no executable mode. Additional public/shared
surfaces must inherit it and pass their own ACL/revocation tests before release.
+395
View File
@@ -0,0 +1,395 @@
# Language Projection Draft
## Goal
Language should NOT affect semantic hierarchy.
Language is treated as:
```text
projection
representation
view
```
rather than containment.
* * *
# Core Philosophy
## URL hierarchy is language-neutral
Paths represent:
```text
semantic location
knowledge locality
human navigation
```
NOT language ownership.
* * *
# Example
Preferred:
```text
/dev/api/auth
```
Avoid:
```text
/ja/dev/api/auth
/en/dev/api/auth
```
because language hierarchy pollutes semantic hierarchy.
* * *
# Important Separation
Layer Meaning Path semantic hierarchy Page UUID identity Revision representation Language projection
* * *
# Internal Model
## Page
Language-neutral semantic object.
```text
Page UUID
```
Example:
```text
Page
├─ Japanese revision
├─ English revision
└─ Chinese revision
```
* * *
# Revision
Language-specific content snapshot.
## `revisions` table
| Field | Meaning |
| --- | --- |
| `uuid` | Immutable Revision UUID |
| `object_uuid` | Parent Page UUID; retained name during the Object-to-Page migration |
| `document_hash` | SHA-256 of the immutable canonical payload |
| `lang` | Canonical BCP 47 language tag or `und` |
| `message` | Commit message |
| `created_at_ms` | Unix epoch milliseconds |
The payload is addressed by `document_hash`; it is not identified by the
Revision UUID.
* * *
# Language Resolution
## Request
```http
GET /dev/api/auth
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
```
* * *
# Resolution Flow
```text
Page UUID
↓
find latest revision(lang=ja-JP)
↓ not found
find latest revision(lang=ja)
↓ not found
find latest revision(lang=en)
↓ not found
find latest revision(lang=campus default)
↓ not found
find latest revision(lang=system default)
↓ not found
find latest revision(lang=und)
```
* * *
# Fallback Philosophy
Language fallback is preferred over URL duplication.
* * *
# Recommended Fallback Chain
Example:
```text
ja-JP
↓
ja
↓
campus default
↓
system default
↓
und
```
Duplicate candidates are removed while preserving order. Invalid language
tags are ignored. `und` is the compatibility projection for revisions created
before language-aware delivery.
* * *
# Zone Language Metadata
Zones may optionally define language affinity.
## `zones`
| Field | Meaning |
| --- | --- |
| `default_lang` | Preferred fallback language |
| `allowed_langs` | Allowed languages |
* * *
# Example
## JP-oriented campus
```text
default_lang = ja
allowed_langs = ja,en
```
* * *
# Global campus
```text
default_lang = en
allowed_langs = *
```
* * *
# Spot Language Metadata
Spot may optionally specify:
| Field | Meaning |
| --- | --- |
| `preferred_lang` | Preferred rendering language |
This influences rendering preference only.
It does NOT change identity.
* * *
# Canonical URL Policy
Canonical URL remains language-neutral.
Example:
```text
/dev/api/auth
```
Language selection is handled at rendering time.
* * *
# Optional Explicit Language URL
Explicit language paths may exist for:
- debugging
- preview
- direct linking
- translators
Example:
```text
/_/lang/ja/dev/api/auth
```
However:
```text
this is NOT canonical
```
* * *
# Why This Design
## Prevents hierarchy pollution
Avoids:
```text
language hierarchy
```
overwriting:
```text
semantic hierarchy
```
* * *
# Benefits
## 1. Stable semantic URLs
The same knowledge object keeps the same path.
* * *
## 2. Shared semantic identity
Multiple languages refer to the same:
```text
Page UUID
```
* * *
## 3. Better multitree behavior
Aliases and bindings remain language-neutral.
* * *
## 4. Better graph compatibility
Semantic relations do not duplicate per-language.
* * *
# Relation to Existing Architecture
This design aligns with:
```text
path != object
```
and extends it into:
```text
representation != object
```
* * *
# Conceptual Mapping
Concept Meaning Path semantic locator UUID identity Revision representation Language projection
* * *
# NDN-like Interpretation
## Name
```text
/dev/api/auth
```
semantic and language-neutral.
* * *
## Content Negotiation
Language selection behaves similarly to:
```text
content negotiation
```
using:
```text
Accept-Language
```
* * *
# UI Philosophy
Language switching should feel lightweight.
Example UI:
```text
[Japanese] [English] [中文]
```
without changing semantic location.
* * *
# Important Principle
Language should not fork the knowledge universe.
Avoid:
```text
ja-wiki
en-wiki
```
style silo fragmentation unless intentionally desired.
* * *
# Current Recommended Direction
Layer Model UI semantic hierarchy URL language-neutral Internal revision projection Identity UUID Rendering Accept-Language + fallback
* * *
# Summary
Language is treated as:
```text
projection
representation
view
```
NOT:
```text
ownership
containment
hierarchy
```
This preserves semantic structure while supporting multilingual knowledge naturally.
+570
View File
@@ -0,0 +1,570 @@
# Architecture Implementation Roadmap
## Principles
### Task management first slice (2026-09-24)
2026-09-25 task CalDAV (`0.8.0`, implemented and fixture-tested, **deployed to app/app2 on 2026-09-26 at 00:24 JST**; [deployment record](../operations/deployments/2026-09-26-task-caldav.md)):
private fixed VTODO collection, revocable read/read-write app passwords with UI,
conditional writes and archive deletion. Real vdirsyncer 0.21.0 / Todoman 4.7.0
discovery and bidirectional sync tests. Date-only deadlines; not full CalDAV
conformance. See [task CalDAV contract and CLI setup](ja/task-caldav.md).
2026-09-25 task follow-up (`0.7.0`, implemented and deployed to app/app2 at 07:07 JST):
daily/tomorrow planning, explicit carryover rescheduling, hierarchy-aware pagination
and parent context, and atomic Wiki-note creation with UUID-bound view/edit actions.
See [daily task / Wiki note contract](ja/task-daily-notes.md). Capacity, bulk family
planning, manual sorting and shared tasks remain open.
2026-09-25 follow-up (implemented, fixture-tested and **deployed to app/app2 at 05:59 JST**; [deployment record](../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)):
- [x] Inline title/status/date editing, independently dated two-level subtasks,
bounded monthly day schedule, home shortcut and Today navigation modal (`0.6.0`).
- [x] Inbox presentation preferences per account/browser, focused expiring toasts,
opt-in return modal, sound presets/volume, notification-only Service Worker.
- [x] Opt-in Web Push: transactional Inbox outbox, revocable session-bound subscriptions,
VAPID, vendor allowlist/DNS pinning, bounded scheduler delivery/retry/expiry and focus acknowledgements.
- [ ] Live OS/browser delivery acceptance with an explicitly opted-in test device
(Chrome/Firefox/Safari), iOS home-screen installation and OS power-saving behavior.
See [active notification contract](ja/active-notifications.md) and
[inline task/day schedule contract](ja/task-inline-schedule.md).
- [x] `organizer.tasks` private per-principal/Domain items and projects, CAS payloads,
atomic head/revision/change journal, conditional writes and idempotent creation.
- [x] Today, Inbox, Backlog, Someday, Review, Completed and Archive; project/task detail,
quick capture, due/planned/review dates, priority, estimate and readable Wiki UUID links.
- [x] Bounded lists/history, EN/JA, theme-aware desktop/mobile dialogs, extension kill switch.
- [x] Typed independent outbox subscriptions; atomic task/project events, bounded journal
migration through the scheduler, no City jobs for task-only changes.
- [ ] Shared collections/assignees, export/recovery and bulk review.
- [x] Opt-in due/planned-date task reminders, atomic reservations/cancellation,
bounded background Inbox delivery, live metadata authorization and badge refresh.
- [x] Private local calendar time-block links, durable retry intents, current event time/ETag lookup, unlink tombstones; imported/shared/public calendars excluded.
- [x] Persistent Pomodoro: start/pause/resume/finish/cancel, one active session per principal, conditional transitions, bounded scheduler completion and Inbox notification.
- [x] Today bounded estimates/current local time blocks/recorded focus intervals, overlap and incomplete-total indicators. Calendar event summaries include an explicitly approved task-title snapshot, never notes.
- [ ] Personal capacity, carry-over and period/project reports; historical focus-span backfill; calendar reminders, notification defaults/quiet hours/digests; Pomodoro personal defaults/cycles and routines.
See [time-block and Pomodoro contracts](ja/task-planning-focus.md) for API, privacy,
two-store recovery, polling limits and remaining work. Canonical calendars and task
DB metadata both require backup. Production app/app2 deployment completed on
2026-09-25 JST; see the [deployment record](../operations/deployments/2026-09-25-task-today.md)
for backup, verification and the observed transient scheduler lock contention.
- [x] Limited private VTODO / CalDAV with vdirsyncer + Todoman file synchronization.
- [ ] Time-of-day deadlines, recurrence/alarms, shared task collections, incremental
sync-token and additional CalDAV clients; dependency graph, tickets and offline UI.
See [Japanese task implementation contract](ja/tasks-implementation.md).
The existing `/v/plan` calendar default is unchanged; tasks start at `/v/plan/today`.
### Calendar subproject (2026-09-22)
- [x] Small-screen/touch calendar navigation, readable week columns and day selector,
scroll-first gestures, compact month counts and VisualViewport-aware editor.
[Mobile contract](ja/calendar-mobile.md): fixture-tested and deployed 2026-09-25; iPhone Safari acceptance pending.
- [x] Initial file-canonical calendar/month snapshots, rebuildable SQLite index,
conditional event CRUD and bounded CalDAV time-range REPORT.
- [x] `/v/plan` year/month/week/day/events/timeline, event dialogs and per-calendar collaborators.
- [x] Per-user default calendar overlays and explicit comma-separated `pretty_name` selection.
- [x] Week/day time grids, configured-timezone day boundaries, zoom through 400% with 5-minute precision,
ETag-protected move/start/end resizing without refetch, equal overlap lanes, drag-range creation,
horizontal rescheduling and `week/list`.
- [x] Read-only ICS polling with interval/conditional GET and bounded external CalDAV REPORT/multiget;
background event queue, encrypted Basic credentials, SSRF guards and failure-safe snapshots.
- [x] Outlook published-ICS projection for METHOD:PUBLISH, VTIMEZONE/TZID, Windows timezone names,
bounded RRULE expansion, EXDATE/RDATE, moved/cancelled RECURRENCE-ID instances and orphaned
exception projections, plus multi-megabyte synthetic fixtures.
- [ ] Recurrence PERIOD/THISANDFUTURE, alarms/durations, provider validation, discovery/OAuth,
configurable synchronization windows and conflict-aware bidirectional synchronization.
- [ ] Full iCalendar temporal semantics (recurrences, timezones, exceptions), CalDAV discovery/client compatibility,
application credentials, synchronization tokens and maintenance/metrics jobs.
- [ ] Group sharing, audited administration, ownership recovery and calendar scheduling/notifications.
See [Japanese implementation contract and limitations](ja/calendar-implementation.md).
The initial supported subset is not a claim of full CalDAV conformance.
System-service plugins are distinct from document adapters. See
[System extensions](system-extensions.md) for implementation boundaries and the next slices.
- [x] Responsive wider bookmark-card grid (viewport-dependent columns).
- [x] Built-in resource.sample event, SQLite history, retention and bounded graphs without foreground collection.
- [x] Separate system-extension catalog and settings area for trusted built-ins.
- [x] Unified execution/resource monitor (running jobs only), paginated job history with lazy logs.
- [x] Protect group owners from ordinary member downgrades and atomically retain an owner during concurrent removal.
- [ ] Transactional activity outbox and Domain/principal recent-edit projections.
- [x] Diary/blog initial built-ins: Page UUID metadata, calendar/recent entries,
categories, read-filtered indices, per-Domain enable/disable and registration UI.
See [initial scope](diary-blog-plugins.md); this is authenticated, existing-Page registration only.
- [x] Diary/blog atomic Markdown new-post composition, transactional metadata/Revision,
embedded-asset freezing, idempotent retry and create/write enforcement.
- [ ] Diary/blog: anonymous metadata approval/feeds,
recent comments and safe resumable tDiary import; declarative time/OS/sunset theme rules.
- [x] Diary/blog per-Domain prefixes, optional keyword URL planner, multiple articles
per day, and authenticated Domain-root diary/blog entry view (2026-09-17).
Legacy Page registration remains available.
- [x] Domain entry-settings dialog and signed manifest v2 provisioning of layout,
diary/blog enablement and prefixes; atomic destination apply and managed edit guards.
- [x] Signed enrollment capability proof and Campus-wide approved-peer v2 preflight
before entry-setting changes; unknown/legacy peers block with a visible explanation.
- [ ] Entry provisioning inside Domain creation, controlled-settings release/retention,
applied-setting acknowledgments and freshness policy.
- [x] Diary/blog dated viewer routes `/v/{kind}/yyyy/mm[/dd]`, `own` presence
filter, legacy-query redirects, and canonical calendar/filter/pagination navigation.
- [x] Local same-Campus diary/blog index/calendar projection without copying articles;
source and destination read-policy filtering, source body/edit links, target write guard.
- [ ] Project article bodies on destination host, approved anonymous projection,
cross-instance source transport/revocation and source-setting federation.
- [ ] Rankings, reactions and moderated Page/inline comment services.
- [ ] Linkding-compatible bookmark-source injection with scoped credentials.
- [ ] Explicit external-search fallback and PagesWiki/GROWI/PukiWiki connectors.
- [ ] S3-compatible Document Store; read-only WebDAV/SSH external collections.
- [ ] Optional SNMP resource collector with target/OID allowlists and SNMPv3 secrets.
- [ ] Third-party system-plugin signature validation, isolated runtime and lifecycle operations.
vim.wasm runtime fixes are on hold by user request; its existing configuration UI is retained.
### Prioritized execution order (2026-09-14)
Feature checkboxes above are not an instruction to bypass the hardening gates.
The execution order is maintained in [Implementation status](implementation-status.md#ordered-next-work).
1. Completed this slice: unified monitor/history UI, bounded/indexed job/log retrieval;
first P0 correction: owner downgrade and concurrent last-owner removal protection.
2. Completed bounded hardening: OIDC/JWKS, inherited-admin revocation,
browser mutation/purpose checks, Domain/Object scope and read filtering;
see the [execution ledger](hardening-execution-2026-09.md).
3. Completed recursive authorized snapshots, literal prefix transactions and
signed manifest/checkpoint atomicity. Remaining write-policy fencing and
content-author trust are gates before public/shared collaboration.
4. Completed PDF/archive metadata jobs, bounded read-policy snapshots,
Object/Revision pagination and improved search; continue lazy City/directory
projection, decoder isolation and durable entry extraction.
5. Transactional activity outbox, actor attribution, idempotent URL reconciliation
and recent-edit projections.
6. Diary/widgets/import and themes, then comments/rankings, external search/bookmarks,
storage connectors and SNMP. HA leases/fencing gate multi-node deployment;
external plugin installation remains disabled until isolation/security gates pass.
- Migrations must preserve existing UUID and path reachability.
- New architecture is introduced in vertical slices with regression tests.
- Reserved authorization features must not be simulated with insecure
allow-all placeholders.
- New collaboration and extension features must use the stable Page UUID,
immutable Revision, Domain-scoped policy, projection-adapter, event, and
scheduler contracts described in
[Platform Extension Architecture](platform-extension-architecture.md).
- SQLite remains a supported single-node metadata backend. HA work must add a
replicated metadata strategy or explicit single-writer fencing; sharing a
live SQLite file over a network filesystem is not an HA design.
## Phase 1 — Identity and projection foundations
- [x] Separate Object creation from Semantic Path binding.
- [x] Rename the implemented District model to Domain.
- [x] Separate Revision UUID from Document SHA-256.
- [x] Add Revision language metadata and fallback selection.
- [x] Move immutable payloads to `documents/sha256/` with a transitional
SQLite compatibility cache.
- [x] Add rsync-like and interactive `path:` / `uuid:` / `rev:` / `asset:`
data administration.
## Phase 2 — Knowledge City topology
Current review: [City reconciliation and navigation](city-review-and-reconciliation.md).
The completed items below are initial implementations. The next City slices are:
- [x] Audit City/autoplan/gen-city and design URL-driven event reconciliation.
- [x] CITY-A named links: parent-qualified Street URLs, ambiguity-safe lookup,
shared search/map/macro links, ancestor authorization, lightweight details,
literal Page URLs and map focus/locality-search regression coverage.
- [ ] CITY-A: per-result authorization, literal Paths, scoped links/names,
shallow/portal inference, manual ownership and idempotent application.
- [ ] CITY-B: transactional mutation outbox → debounced, durable City queue
consumer; scheduled/manual repair through the same pipeline.
- [ ] CITY-C: stable fabric, Worker/cache, connected roads, bounded lazy
projection and capacity-safe picking targets.
- [ ] CITY-D: icon/modal creation/settings, arrow/WASD/HJKL navigation,
focus/history handling and i18n browser regressions.
- [x] City label follow-up: visible resting labels, horizontal Street names,
retained hover/focus highlighting and working label toggle; normal/popup tests.
- [x] Manual City organization: display-title modal, Ctrl/Command selection,
existing/new Spot merge, Street relocation retaining Page URLs, transactional
validation and manual-inference overrides; see [contract](city-organization-ui.md).
- [x] Immersive City follow-up: focused Spot courtyards and surrounding Page
buildings, nonoverlapping bounded/paginated close-ups, themed architectural SVG,
modal utility menu and directory navigation; normal/popup regressions. See
[projection and limits](city-immersive-map.md); CITY-A–D gates remain open.
- [x] Filter City map/details/macros/badges by readable boundaries and Pages;
recompute visible portals/counts/relations and use private responses.
- [x] Local gen-city Worker with time/input/output/cache bounds, cancellation
and retry, plus spatial Arrow/WASD/HJKL navigation in normal/popup modes;
see [worker and navigation](city-worker-navigation.md).
- [x] One-connection-safe bounded City snapshots and literal Path
containment/overlap/context/health; true lazy Page pagination remains open.
- [x] Define Campus identity and defaults.
- [x] Define Domain ownership by Campus.
- [x] Scope Semantic Paths by `(domain_uuid, path)`.
- [x] Add local/remote Domain placement.
- [x] Add absolute cross-Domain link helpers.
- [x] Add standalone/controller/managed Campus authority modes.
- [x] Scope non-topology configuration by Domain.
- [x] Scope Recent Objects by selected Campus and Domain.
- [x] Record controller-selected Domain instance FQDN.
- [x] Add hashed enrollment tokens and fingerprinted instance registration.
- [x] Add pending/approved/revoked instance placement selection.
- [x] Add external Campus bootstrap enrollment.
- [x] Add Managed Campus health status and detach actions.
- [x] Add signed Campus manifest reconciliation.
- [x] Implement ZoneTree nodes for Quartier and Street.
- [x] Implement Spot identity and ZoneTree pointers.
- [x] Implement SpotGraph Page bindings and MagicPage traversal.
- [x] Define Quartier planning, Street routing, Spot locality, topology
invariants, projections, APIs, policy inheritance, and delivery slices.
- [x] Add the initial topology schema, monotonic Domain topology version,
topology events, and Quartier/Street/Spot creation stores.
- [x] Add the initial interactive `/v/city` SVG guide map and authorized map API.
- [x] Add SpotPage/MagicPage edges, Viewer locality badges, Spot detail Page
lists, and initial typed SpotGraph relation visualization.
- [x] Add Quartier/Street/Spot detail projections, transactional Street/Spot
moves, ordering, and reversible SpotPage/SpotRelation edge removal.
- [x] Add planning preview/apply, reversible before/after event payloads, and
city health analysis.
- [x] Add `/v/city` map and locality breadcrumbs.
- [x] Add locality-scoped search and topology macros.
## Phase 3 — Projection runtime
- [x] Formalize the initial Viewer projection adapter registry and contract.
- [x] Route Viewer and semantic editor selection through adapters.
- [x] Route preview through adapters, including bounded text and CSV projections.
- [x] Route bounded print layouts through adapters at `/_/view/print/<address>`.
- [x] Route the semantic Viewer through the initial adapter registry.
- [x] Add bounded text retrieval backed by seekable Document Store reads.
- [x] Defer PDF page rendering to idempotent scheduler jobs with retrying
Viewer delivery and bounded PDF page-count commands.
- [ ] Defer non-ZIP archive metadata and entry extraction to cached, bounded
scheduler projections.
- [x] Persist PDF page-count and non-ZIP metadata via shared scheduler jobs,
bounded immutable-hash cache and localized pending/retry views.
- [ ] Persist seekable non-ZIP extracted entries with quota/lease/Range and
archive-bomb controls; move ZIP central-directory work off the request path.
- [x] Add bounded structural JSON retrieval by immutable Revision and lazy
JSON-Pointer expansion without unmarshalling the complete payload.
- [x] Separate authoring and projection macro transpilation so HTML-to-Markdown
round trips preserve `children` while Markdown previews render it.
- [ ] Generalize the authoring/projection macro contract to typed extension
macros with versioned round-trip and projection tests.
- [x] Add ZIP/archive directory and Debian metadata adapters.
- [x] Add a bounded CSV table adapter.
- [x] Add the bounded `@excalidraw/excalidraw` hosted Viewer plugin with an
isolated immutable-Revision contract and safe built-in Canvas fallback.
- [x] Separate built-in projections from Domain-scoped hosted adapter plugins.
- [x] Restrict hosted adapter targets to HTTP(S) services such as vim.wasm or
a separately deployed editor gateway.
- [x] Define and implement one-use launch tickets and optimistic Revision
write-back with a reference hosted-editor gateway.
- [x] Connect an internal code-server instance to the hosted-editor Gateway,
with session workspace materialization and autosave Revision write-back.
- [x] Connect a cross-origin-isolated vim.wasm frontend to the hosted-editor
Gateway contract with hierarchical MEMFS loading and Revision write-back.
- [ ] Evaluate a local helper, temporary workspace, and executable allowlist
before enabling native applications such as Vim or VS Code.
- [x] Freeze embedded mutable Asset HEADs into immutable Document hashes on
Revision save and retain authorization references from the containing Page.
- [x] Scope mutable Asset addresses and management metadata by Domain.
- [x] Add typed Asset MIME/filename/size metadata and immutable HEAD history.
- [x] Add administrator HTTP create/update/delete with ETag preconditions.
- [x] Add the initial Asset management panel under Domain configuration.
- [x] Add Asset HEAD history/restore and Page/Revision dependency-detail UI.
- [ ] Add Asset retention controls, policy-matrix capabilities, and general
audit-outbox integration as specified in `asset-model.md`.
- [ ] Add a capability-checked mutable Asset authoring-preview endpoint and
typed `srcset`/CSS resource resolution without allowing live Asset URLs into
stored Viewer output.
- [x] Add authorized immutable object retrieval at `/_/obj/sha256:<hash>`,
limited to Documents referenced by a readable Path in the current Domain.
## Navigation and home layouts
See [Home layouts and sidebar design](navigation-home-sidebar.md).
- [x] Vendor Hack Nerd Font for Browser and Tree without a runtime CDN dependency.
- [x] Add Domain-scoped classic, centered-search, and search/bookmark home layouts.
- [x] Keep home search global to the current Domain even when rendering `/top`.
- [x] Scope `/v/tree/{path}` to the requested subtree with breadcrumbs and cached expansion.
- [x] Limit Browser revision lookups to displayed files and repair missing revision indexes.
- [x] Define a shared sidebar layout, state ownership, and bounded children API contract.
- [ ] Implement the shared sidebar and authorized, paginated lazy navigation API.
- [x] Group configuration navigation and split scheduler, queue, logs, resources,
authentication providers, and adapter-specific settings into separate panels.
- [x] Add accessible themed switches and a Domain bookmark manager for Paths/URLs.
- [x] Restore public application assets and align compact/legacy editor paths.
- [x] Manage bookmarks from home; section cards and permission-filtered async child links.
- [x] Refine bookmark management into an icon-launched modal and section-card editor with group operations.
- [x] Add admin-only Domain vimrc/colorscheme upload, download/reset, session-scoped delivery and safe-mode recovery.
- [x] Explicitly load hosted Vim configuration, bundle its font and add a pure-Vimscript navigation plugin; verify the real Wasm runtime.
See [home navigation and hosted Vim](home-bookmark-sections-vim.md).
- [x] Add bounded, visibility-aware live resource graphs without a CDN dependency.
- [x] Repair Asset GET authorization and align metadata/history/reference reporting.
- [ ] Add versioned adapter-specific settings schemas and secret-field handling;
see [Configuration panels](configuration-panels.md).
- [ ] Add a transactional directory index and batch authorization for large hierarchies.
## Phase 4 — Identity and authorization
- [x] Normalize password, TOTP, OIDC, and magic-link authentication into Principals.
- [x] Add the initial direct Membership, Role, and positive-grant schema.
- [x] Add the initial Domain-level Capability evaluation with default deny.
- [x] Replace capability inference from URL words such as `delete` and `rename`
with a centralized typed endpoint policy classifier; deny undefined mutations
in reserved namespaces and method-close exact API routes.
- [ ] Complete typed object/path target resolvers for derived views and remove
the remaining handler-specific authorization exceptions.
- [x] Resolve raw, windowed text, PDF-page, preview-cache, print, Object,
Revision, history, and diff reads through their source Object/Path grants.
- [x] Filter Tree, Browser, Search, Preview listings, and asynchronous children
results per visible Path without returning hidden child counts.
- [x] Scope the initial Object list and Revision list API responses to the
current Domain and readable Object/Path grants.
- [x] Declare JSON/multipart target resolution as handler-owned policy and
remove route-name bypasses from middleware; enforce every expanded source
and destination Path for recursive rename, copy, and delete operations.
- [x] Bind hosted adapter sessions to the issuing Principal and re-check
current read/write grants on every workspace/content operation.
- [ ] Move multipart/JSON source-and-destination mutation checks into typed
decoded-request objects shared by middleware and handlers.
- [x] Add cookie-session CSRF and credential-type separation (legacy unprefixed
sessions expire normally); POST-only logout and live membership checks.
- [x] Verify OIDC issuer JWKS signatures/claims/browser state and reject
ambiguous email matches or conflicting external-identity binding.
- [x] Add Domain-scoped LDAP/LDAPS authentication with service search bind,
escaped exact-one user lookup, user-DN password bind, encrypted secrets,
immutable provider identity, bounded time/concurrency, optional member-only
provisioning, saved-configuration test UI, and Japanese/English labels.
- [x] Revoke derived Campus-admin grants transactionally without deleting
independent local grants or regenerating removed bootstrap authority.
- [x] Scope foreign/unbound Object authority and record atomic API creation
provenance; check all local aliases for global Object purge.
- [x] Revalidate zombie eligibility within the purge write transaction; scope
HTTP/config cleanup by Domain provenance and reject orphan-producing writes.
- [x] Bound Object/Revision metadata APIs with cursor pagination and batched
read checks; compact search exposes full Path and safe matching excerpts.
- [x] Common inert HTML projection boundary, bounded macro expansion, application
CSP and cross-account browser denial tests; preserve canonical authoring bytes.
See [policy and compatibility](html-projection-trust.md). No executable mode.
- [x] Gate the first anonymous semantic/raw slice on explicit current-revision
manifests, inert HTML, mutation invalidation and denial/revocation tests.
- [ ] Extend those gates to anonymous discovery/dependencies and delegated
shares with full impact-aware mutation/alias handling.
- [ ] Add Domain groups, group Role bindings, and `/g/` management surfaces.
- [ ] Add explicit OIDC/LDAP group mappings and policy-version invalidation;
LDAP authentication must remain usable without enabling group synchronization.
- [ ] Add auditable policy decisions.
- [ ] Add an authorized effective-permission inventory for Campus, Domain,
Quartier, Street, Spot, Page, share, group, Role, and Principal scopes.
- [ ] Add explicit anonymous-read policy grants without weakening default deny.
- [ ] Add signed PSK federation of selected Principal, group, Role, and grant
records between Domains, including origin, sequence, conflict, revocation,
and `campus_admin` inheritance policy.
## Cross-phase enabling work — Extension seams
These items must land before the later feature that depends on them. They are
listed separately because they replace concrete single-feature assumptions
without changing user-visible Page identity.
- [ ] Put filesystem `DocumentRoot` access behind the seekable, content-addressed
Document Store interface before adding S3 or multi-node payload placement.
- [ ] Generalize topology/event-job records into a versioned transactional
Domain event outbox before notifications, feeds, metrics, comments, or DR
consume mutation events.
- [ ] Add a typed extension manifest and provider registry before adding third-
party transpilers, widgets, scanners, storage backends, or themes.
- [ ] Inventory process-local sessions, caches, preview slots, scheduler state,
adapter workspaces, and signing material before declaring LB/HA support.
- [ ] Add typed annotation/reaction/assessment stores keyed by Page and Revision
UUID before exposing comments, likes, or quality evaluation in Viewer HTML.
- [ ] Add privacy, retention, moderation, audit, export, and deletion contracts
before collecting view history, engagement, comments, or notification data.
## Phase 5 — Delegation
- [ ] Add Macaroon root-key rotation and verification.
- [ ] Implement attenuation caveats.
- [x] Add server-rendered OGP/X link cards for already-public Page/home/City
views, absolute configured-host URLs and a cached PNG fallback; retain
authentication and private metadata suppression. See [social cards](social-link-cards.md).
- [ ] Add read-only share projections under `/s/`.
- [x] Add Quartier/Spot owner appointments and governance dialogs; subordinate
publication policies may only narrow superior ceilings. Keep permission to
publish separate from actual publication and preserve authenticated ACLs.
See [detailed ownership/publication design](locality-publication-ownership.md).
- [x] Add named user/group read and read/write settings with ancestor caps,
stable identities, next-request membership checks and recovery authority.
Initial namespace guards freeze protected moves/aliases and City structure;
replace them with impact-aware mutation workflows in the next slice.
- [x] Add bounded explicit current-revision approvals and a separate inert
anonymous semantic Viewer/raw-media path with safe OGP and revocation tests.
No automatic activation of drafts or future edits. See
[exact scope and follow-ups](locality-access-publication.md).
- [x] Public Page breadcrumbs, asynchronous children, read-only tree and filtered
City navigation; database-generation cache invalidation and fresh authenticated
read filters. Remove public download controls; reserve isolated presentation
for share URLs. See [navigation contract](public-navigation.md).
- [x] Add owner-managed `/u/{username}` audiences for profile metadata, avatar,
Wiki root and descendants, plus narrowing subtree overrides, a dedicated
anonymous reader/navigation snapshot, immediate superior-ceiling revocation,
alias/UUID/Revision fences and atomic rename tracking. Keep `/u/` out of the
global anonymous tree. See [user-space publication](user-space-publication.md).
- [x] Harden anonymous navigation: public root/virtual-folder landing, read-only
directory, Page/children round trips, tree expand/collapse/filter/keyboard
controls, mobile header and City exits, cancellable bounded children loading,
retries and progressive pagination; retain exact-publication boundaries.
- [x] Explicit Street/Spot automatic publication with inherited manual-approval
boundaries, confirmed impact previews, live publisher/ACL checks and cache
invalidation. Existing scopes remain opt-in; see
[implemented slice and limits](automatic-publication.md).
- [ ] Immutable review requests, scoped approvers, durable outbox delivery and
reviewer notification Inbox. Continue the remaining AP-1 through AP-6 work in
[approval workflow design](publication-approval-inbox.md); automatic publication
does not implement the human approval workflow or silently activate drafts.
- [ ] Complete dependency/alias-aware publication previews, large-site review
and per-capability audiences; current approvals exclude aliases, restricted
user/group scopes and dependencies rather than implicitly publishing them.
- [ ] Fence locality publication against alias/move/merge/archive/import bypass,
and share one anonymous read evaluator across safe Viewer/media, City/search,
children and OGP. Gate enablement on HTML isolation and revocation tests.
- [ ] Add share management, expiry, revocation, access audit, optional password,
download prohibition, language/path restrictions, and QR-friendly links.
- [ ] Ensure share credentials are separate from login, adapter, federation,
and API bearer credentials.
## Phase 6 — Activity, notification, and collaboration
- [ ] Formalize a Domain-sequenced event outbox for Page, Revision, Path,
topology, policy, share, comment, reaction, quality, and federation events.
- [ ] Add Page/Spot/Street/Quartier subscription and change-notification rules.
- [ ] Add a per-Principal notification inbox with unread state, grouping,
filtering, retention, cursor pagination, and authorization-safe deep links.
- [ ] Add delivery channels for Web inbox, email digest, webhook, and future
push adapters, with retry/dead-letter state in the event scheduler.
- [ ] Add recently edited and recently viewed Page projections; keep private
activity private and provide retention/opt-out controls.
- [ ] Add privacy-aware Page view counters with bot filtering, idempotent event
aggregation, time windows, and “most viewed” projections.
- [ ] Add Page reactions/likes without modifying immutable Revision payloads.
- [ ] Add document-quality assessments with rubric/version, reviewer identity,
score history, and machine/human provenance.
- [ ] Add Revision-anchored inline comments with text-range anchors, context
hashes, orphan/rebase handling, resolution state, and permissions.
- [ ] Add Page-level threaded comments below the document with moderation,
mentions, subscriptions, edit history, and soft deletion.
## Phase 7 — Knowledge City services
- [ ] Complete Campus landing, Domain catalog, controller status, announcements,
shared navigation defaults, audit, export, and delegated Campus governance.
- [ ] Complete Quartier charter, entrances, localized signage, curators,
announcements, scoped activity/search, subscriptions, health, merge/split,
export/import, and policy-default surfaces.
- [ ] Complete Street route intent, sections, Inbox, landing, activity,
maintenance queue, subscriptions, merge/split/promotion, and policy override.
- [ ] Complete Spot generated portal, curator workflow, dynamic sections,
watchers/digests, backlinks, shortest routes, health states, split/merge,
archive/successor, and machine-readable context payload.
- [ ] Add Campus/Quartier/Street/Spot notification and permission inventory
integration without turning locality into Page identity.
## Phase 8 — Controller disaster recovery and high availability
- [ ] Add controller manifest journal replication to a designated DR instance,
including signing-key rotation/escrow, encrypted backup, sequence verification,
last-known-good snapshots, RPO/RTO reporting, and restore drills.
- [ ] Add controller leader election or manual promotion with fencing so two
controllers cannot publish the same Campus sequence concurrently.
- [ ] Add managed-instance controller failover using a pinned set of controller
identities and an auditable promotion epoch.
- [ ] Separate process-local cache/session/job state from canonical state and
define shared/replicated backends required by multiple application nodes.
- [ ] Add health, readiness, graceful drain, idempotency, forwarded-origin
validation, and node identity endpoints for load balancers.
- [ ] Add an LB reference deployment with TLS termination, WebSocket support,
upload limits, no mandatory sticky session, and failure tests.
- [ ] Add an HA metadata backend or a fenced single-writer/replica design;
never mount the writable SQLite database concurrently from multiple nodes.
- [ ] Add Document Store replication/read-repair and background-job leases so
only one node performs a claimed task.
- [ ] Exercise node loss, controller loss, network partition, stale replica,
key rotation, and rollback in automated fault tests.
## Phase 9 — Content composition and extension runtime
- [ ] Evaluate tasks/tickets, an organizer with calendar/contact interoperability,
RSS/Atom reading and FreshRSS/newsboat integration, IMAP mail-to-Wiki and
incremental HTML editor improvements. Full WYSIWYG remains
an open decision, not a commitment. See the design-only
[organizer and editing ideas](organizer-and-editing-ideas.md); these are not part
of the current implementation batch. The detailed design has since been expanded
in the [Japanese handbook](ja/index.md), chapters 12–17; implementation remains
unchecked and follows [the dependency-ordered plan](ja/roadmap.md).
- [ ] Add a versioned transpiler registry that converts PukiWiki, Redmine,
DokuWiki, MediaWiki, and future source syntaxes into canonical HTML while
preserving the original source as immutable metadata or a related Revision.
- [ ] Complete Markdown round-trip guarantees and record compiler ID/version,
warnings, source map, and canonicalization result on every conversion.
- [ ] Add Excalidraw and draw.io canvas projections with immutable asset
freezing and configured hosted-editor actions.
- [ ] Add Kroki and PlantUML diagram adapters with bounded input, pinned renderer
version, cached immutable output, timeout, and network policy.
- [ ] Add nwdiag as a bounded network-diagram projection and editor adapter;
support static SVG fallback, pinned renderer versions, and explicit source
import/save without executing authored code.
- [ ] Add a widget/oEmbed registry for Spotify, YouTube, SoundCloud, and future
providers with Domain allowlists, consent placeholders, CSP sandboxing,
privacy mode, and no arbitrary document-authored script execution.
- [ ] Add administrator-packaged widgets with signed manifests, semantic
versioning, capability declarations, resource quotas, and disable/rollback.
- [ ] Add a generated top-page composer using authorized queries, static blocks,
recent work, recent views, popular Pages, featured City entrances, and feeds.
- [x] Add initial diary/blog template/query/navigation projections over ordinary
Pages, not a new Page identity or date-dependent storage hierarchy. Registration
metadata follows Page UUID; atomic new-post composition, local Domain projection,
dedicated public article routes/navigation and RSS 2.0 are implemented.
Remaining federation/metadata/Atom work is in the [follow-up plan](diary-blog-plugins.md).
- [ ] Add directory-scoped RSS/Atom feed widgets with scheduler fetching,
conditional requests, sanitization, per-host limits, caching, and provenance.
- [ ] Add a bounded CSV table macro and CSV editor projection. RFC 4180-compatible
CSV remains the interchange baseline; ODS is a separate multi-sheet adapter.
- [ ] Add Reveal-compatible slide projection adapters for HedgeDoc and Slidev,
plus a CSS-only scroll-snap/print editor fallback with explicit import/save.
- [ ] Add custom theme packages with inheritance, tokens, preview, validation,
CSP-safe assets, versioning, export/import, and one-click rollback.
## Phase 10 — External storage, inspection, and ecosystem
- [ ] Define a Document Store backend interface preserving SHA-256 identity,
seek/range reads, atomic put-if-absent, integrity verification, and streaming.
- [ ] Add S3-compatible immutable Document storage with multipart upload,
server-side encryption, credential isolation, lifecycle policy, replication,
local cache, and read-after-write verification.
- [ ] Keep metadata, mutable configuration, and secrets out of the Document
Store; external object keys must never replace Document SHA-256 identity.
- [ ] Add asynchronous file inspection states (`pending`, `clean`, `suspicious`,
`malicious`, `error`, `expired`) and quarantine-aware authorization.
- [ ] Add MWDB/Karton integration through a bounded inspection adapter and event
queue; Viewer/download policy must fail closed where a Domain requires audit.
- [ ] Record scanner engine/version, signatures, hashes, timestamps, verdict
provenance, rescan policy, administrator override, and audit events.
- [ ] Add an extension catalog/API for projection, editor, transpiler, widget,
notification, inspection, storage, search, and theme providers.
- [ ] Add typed IPAM, DNS zone/record, and inventory/asset extensions with
approval-gated provider writes, dry-run, etag checks, secrets, audit, and
bounded queue execution.
- [ ] Add extension signature verification, capability review, compatibility
ranges, install/upgrade/disable/rollback, health, logs, and resource quotas.
Each phase requires schema migration, rollback analysis, and tests before the
next phase begins.
+401
View File
@@ -0,0 +1,401 @@
# Implementation status and hardening backlog
For the consolidated current reading order, use the [Japanese handbook](ja/index.md)
and [decision register](ja/decisions.md). Dated entries below preserve history;
older statements about missing anonymous navigation, blog publication or RSS are
superseded by the newer slices, not additional unfinished implementations.
This document is a working handoff for the current repository state. It is
based on the implementation-roadmap, architecture documents, and a static
review of the handlers and stores. Checked roadmap items describe a usable
first slice; they do not imply production-ready federation, HA, or extension
security.
## Current state
2026-09-25 task reminders: explicit per-task due/planned-date switches and a local
notification time now schedule owner-only Inbox reminders. Reservations are updated
in the source transaction; the bounded scheduler rechecks current state/authority,
skips previous-day catch-up, and commits Inbox insertion plus acknowledgment together.
Titles are projected under current authorization rather than copied into notices.
Notification badges refresh on visible pages without reload. Calendar reminders,
quiet hours, digests and external delivery remain pending. See [contract](ja/task-reminders.md).
2026-09-24 outbox follow-up: City now subscribes only to relevant page/revision/path/object
events, with independent consumer checkpoints rather than shared processed flags.
Per-type high-water marks avoid repeated full-history discovery. Task/project mutations
append metadata-only events in their source transaction; a bounded scheduled bridge
replays the earlier task journal idempotently. Notification delivery and retention are
not included. See [delivery contract](ja/outbox-delivery.md).
2026-09-24 task first slice: private `organizer.tasks` items/projects, Today/Inbox/
Backlog/Review/Completed/Archive UI, conditional updates, idempotent create,
immutable CAS revision payloads and UUID-based Wiki references are implemented.
Ownership is distinct from Wiki ACLs; even Domain administrators cannot read
another principal's tasks through these endpoints. The local atomic change journal
is now connected to the common outbox, but notification delivery, time-block/calendar integration, Pomodoro,
sharing and VTODO synchronization remain follow-ups. SQLite metadata and the
Document Store must be backed up together. See [contract and remaining work](ja/tasks-implementation.md).
2026-09-19 outbox foundation: `activity_outbox` now has a persistent, bounded
envelope with Domain-local monotonic sequence numbers, actor/target references,
idempotency keys, retry state and pending-page retrieval. The append API is
transaction-bound and deliberately does not authorize or project payloads.
Page creation and Revision writes now append through this envelope in their
source transactions. Path rename/delete and Object purge are also recorded;
Domain-local consumer checkpoints are durable and monotonic. A debounced City
consumer now reconciles pending URL events through the scheduler and advances
its checkpoint only after a successful plan. Recipient-scoped notification Inbox
storage and an authenticated list/read API are now implemented with idempotent
deduplication and keyset pagination; approval request producers, reviewer UI and
delivery workers remain pending, so this is not yet a completed activity pipeline.
Street/Spot automatic publication is opt-in through the governance dialog. Current
and future eligible heads follow the pinned Path boundary with live audience and
enabling-actor authority checks. Domain/Quartier/Street/Spot manual-only floors narrow
it; anonymous navigation/blog projection/RSS/share readiness follow the same policy.
Existing scopes stay unchanged. Reviewer/Inbox and policy federation remain pending;
see [automatic-publication.md](automatic-publication.md).
Local diary/blog projection first slice: Campus admins select source Domain and prefix
inside the entry dialog. Same-Campus/local placement only, no copied content; both
Domains' read policies filter private metadata; editing stays on the source Domain.
Target article writes are rejected. Anonymous projection indexes/calendars now derive
only from approved source Paths/Revisions, never private registration metadata.
Dedicated-domain links now open `/YYYY/MM/DD[/keyword]` on that host with sanitized
published bodies, calendar/month/adjacent-article navigation, target Domain branding
and `/rss.xml` (20 items). Registered titles now explicitly inherit Page publication
visibility; category/owner/registration date stay private. No cross-instance transport,
source configuration federation or automatic cross-Domain session sharing yet.
RSS now includes sanitized, absolute-URL HTML in `content:encoded` with bounded
generation and exact publication rechecks. Authenticated `/v/{blog|diary}/-/new`
pages reuse atomic composition. Post completion offers X sharing with configured
projection-domain URLs, target selection and unpublished-link warnings; no automatic
social posting, publication grants or credentials are added.
Domain entry provisioning is implemented in source: Campus-admin dialog per Domain,
explicit allowlisted settings, signed manifest v2 when settings are present, and
transactional apply together with Domain snapshot/checkpoint. Legacy manifests without
entry settings remain v1. Destinations must be upgraded before activating v2 settings;
signed enrollment capability proof and Campus-wide preflight are implemented.
Create-form integration, apply acknowledgments/freshness and control-release/GC remain
pending. Managed nodes cannot override entry settings locally. No new public grants.
Atomic diary/blog composition is now implemented in source: Markdown composer,
create/write checks inside the writer transaction, Page/Path/Revision/article/journal/
receipt atomicity and idempotent retries. Shared Revision insertion and asset freezing
are reused. Anonymous article-index approval, City/notification outbox dispatch,
receipt retention and application acknowledgments remain pending. Existing
two-step editor/registration is optional, not the only new-post workflow.
2026-09-17 URL/entry slice (source implementation): per-Domain diary/blog prefixes,
date/keyword URL planner, same-day multiple diary entries, and home_layout diary/blog
rendering at `/`. Placement label shortened; placement identity remains separate.
The planner is read-only and does not reserve Paths. Editor save and registration
remain separate in the legacy flow; public calendar approval is still TODO.
Existing article Paths are not migrated.
Diary/blog initial slice: `content.diary` and `content.blog` are separate trusted
built-ins with Domain enable/disable settings, Page UUID-bound metadata,
calendar/recent entries/categories, registration/update/unregister dialogs and
fresh read filters. Disabled by default; indices require authentication and
registration does not publish a Page. Public index
approval/feeds, comments and tDiary import remain explicitly deferred; see
[detailed design](diary-blog-plugins.md).
2026-09-16 anonymous navigation hardening: public root and virtual parents now
offer safe directory landing pages, with read-only `/v/browser` and separate
Page/children links. Trees support all/per-folder expand/collapse, name/Path
filtering and keyboard navigation. Responsive public headers, direct City exits,
bounded/abortable asynchronous listings, retry and no-JavaScript pagination are
implemented. No additional publication or approval policy is enabled.
2026-09-16 navigation follow-up: approved public Pages now expose filtered
children/tree/City navigation and breadcrumbs, without a download button.
Database generations invalidate bounded metadata caches; authenticated filters
remain request-scoped, including group revocation on unchanged cached data.
Private parent bodies/titles are not exposed through structural folders. See
[navigation](public-navigation.md). Hierarchical approval requirements and the
reviewer workflow remain [designed and TODO](publication-approval-inbox.md),
while the reusable recipient Inbox API is available but not populated by approval
requests. Approval request subjects, decisions, generation fencing and bounded
expiry sweeps are persisted, but reviewer eligibility and decision UI are not
exposed; the current explicit approval workflow remains in force.
2026-09-14 user/group and anonymous follow-up: named local user/group read or
read/write settings now intersect ancestor caps, resolve stable subject IDs and
observe live membership. Explicit bounded current-revision approvals enable a
separate inert anonymous semantic Viewer and raw-media path with revocation and
OGP. Existing visibility is unchanged until configured. Important first-slice
limits: authenticated ACLs freeze protected namespace/City structural changes;
anonymous edits require reapproval, and discovery/dependencies remain private.
See [implementation contract and remaining tasks](locality-access-publication.md).
2026-09-14 locality governance: scoped Quartier/Spot co-owner appointments,
versioned publication-cap drafts, transactional authority rechecks, local audit
records and themed Japanese/English settings dialogs are implemented. Domain
ceiling is in the City Map utility menu. The subsequent bounded anonymous slice
and coarse namespace fences are described above; complete impact-aware
mutation/dependency handling remains a next gate. See
[exact first-slice scope](locality-publication-ownership.md).
2026-09-14 P0 HTML remediation, extended 2026-09-23: normal
Viewer/home/profile/object/history/print and both Editor previews use the
`controlled-v2` allowlist with application CSP. External resources remain
default-deny; Domain administrators may approve exact HTTPS image URLs or
SHA-256-pinned CSS/JavaScript URLs through the shared Projection/CSP policy.
Canonical bytes are preserved; authored scripts/styles/frames are not activated.
Diagram cache reads recheck Domain/Path authority and sandbox SVG. See
[contract, compatibility and tests](html-projection-trust.md). Ownership/public
activation remains separate work, not implicitly enabled by this security fix.
2026-09-14 publication governance design: explicit Quartier/Spot owners may
administer publication only within superior ceilings; appointment authority,
cap-vs-publication semantics, mutation/alias fencing and the release sequence
are documented in [locality ownership](locality-publication-ownership.md).
The owner API/UI and draft policies have subsequently been implemented as above;
production visibility has not been changed.
2026-09-14 social-card follow-up: already-public semantic Pages, home layouts
and City views now emit OGP/X metadata with bounded canonical-text summaries,
safe absolute URLs and a common PNG cover (original images for image documents).
Enforcing domains retain authentication and suppress content-card metadata;
no visibility policy was changed. See [contract and limits](social-link-cards.md).
2026-09-14 City reference follow-up: parent-qualified readable Street URLs now
replace ambiguous name-only links in map/search/macros. Details require ancestor
read permission and fetch only the requested node; map focus and locality search
work for Quartier, Street and Spot. Literal Page link encoding is shared by the
map and its inspector. See [read integrity](city-read-integrity.md).
2026-09-14 City/search options follow-up: metadata-only Quartier/Street/Spot
matches appear ahead of Pages, with visible ancestor context and safe links.
Search now supports file categories, one extension, and Domain-local calendar
date ranges over creation/update times. Filters run before candidate limits;
City and Page reads share the existing deadline. See
[search options and their exact semantics](search-results.md#city-first-results-and-search-options).
2026-09-14 search timeout follow-up: corrected a production Path-first repeated
FTS scan and costly snippet generation. Input/time-bounded optional excerpts
now preserve search results; query-plan and realistic-volume regressions plus
read-only live-data timing cover the original blind spot. See
[search correction](search-results.md#timeout-regression-and-correction-2026-09-14).
2026-09-14 hardening follow-up: authentication and inherited authorization,
recursive mutations, federation snapshots and garbage collection now have
bounded, denial/concurrency-focused regression coverage. City generation and
PDF/archive metadata work are off the request/rendering path; search and history
have bounded, clearer projections. See the [execution ledger](hardening-execution-2026-09.md)
for validation/deployment and explicit deferrals. The subsequently corrected
normal HTML boundary is recorded above; broader publication gates remain open.
2026-09-14 City UI follow-up: Spot clicks now explore their courtyards, with
surrounding Page links, bounded nonoverlapping close-ups and a modal utility
menu. Manual title/selection/merge/move controls remain available. See
[City projection and its remaining limits](city-immersive-map.md).
2026-09-13 follow-up: execution and resource panels are now one monitor with only
running jobs. Completed jobs and lazy, paginated logs share a history panel.
Active queue counts avoid scanning completed history; job queries use indexed
status filters and keyset pagination. Legacy `panel=resources` resolves to the monitor.
The first resumed hardening task protects group owners from ordinary update
downgrades and checks last-owner removal within the DELETE itself (including
concurrent removals and manager authority against the target's current role).
Current follow-up adds viewport-responsive bookmark columns, persistent
background resource monitoring, and a separate trusted system-extension
catalog. Other system services are designed and sequenced in
[System extensions](system-extensions.md); third-party plugin execution is
not yet enabled. vim.wasm runtime work is paused at the user's request.
Latest UI follow-up: application asset authorization and `/e/` target decoding
are corrected; home bookmarks support admin management, section cards and
bounded asynchronous child links. Hosted Vim now explicitly loads its vimrc,
local font and pure-Vimscript navigation plugin. See
[implementation and remaining limits](home-bookmark-sections-vim.md).
Viewer shortcut follow-up: `e/f/v/c/u/s/p` and the four Ctrl-arrow navigation
bindings are implemented in `static/js/viewer-shortcuts.js`. They suppress
themselves while typing or inside dialogs; sharing copies the current canonical
URL and opens a user-confirmed X Intent. The X action is cataloged as the trusted
builtin `sharing.x` extension; it does not grant publication or create a share
credential. Permission shortcut behavior depends on the City governance context.
The repository currently has working first slices for:
- Campus and Domain scoped semantic paths, local/remote placement, controller
enrollment, signed manifest reconciliation, and the initial Knowledge City
topology/map UI.
- UUID/Object, immutable Revision, SHA-256 Document storage, language fallback,
asset HEAD/history, bounded text and JSON projections, archive/CSV/EML/PDF
adapters, and hosted code-server/vim.wasm/Excalidraw adapters.
- Password/TOTP sessions, OIDC, LDAP/LDAPS, and SMTP magic-link flows, Domain
capabilities, built-in campus/domain administrator groups, group permission
profiles, and a centralized endpoint policy classifier.
- Persistent event jobs with priority, retry, cancellation, concurrency
settings, preview generation, import jobs, and manual scheduler controls.
The current deployment is a single writable SQLite application node plus a
managed external-domain node. This is a supported development topology, not
HA: canonical metadata, session revocation, scheduler claims, and adapter
state are still process/instance local.
## Confirmed corrections (2026-09-14)
The [execution ledger](hardening-execution-2026-09.md) records verification and
deployment separately. Completed, regression-tested slices include:
- OIDC issuer JWKS signatures, algorithm/claim checks, browser-bound state,
bounded key/discovery fetches and account-binding collision rejection;
[verification contract](oidc-verification.md).
- SMTP connection/protocol deadlines, bounded replies, STARTTLS, mailbox/header
validation, one-use challenges and live membership checks;
[delivery limits](smtp-magic-link-hardening.md).
- Campus-admin provenance and transactional derived-membership revocation while
retaining independent local grants; [inheritance contract](campus-admin-revocation.md).
- Same-origin browser mutation protection, POST logout, typed browser/API
credentials, atomic session-state checks and request-scoped batch Path reads;
[request boundaries](browser-request-security.md).
- Domain scope for Object reads/saves/binds, exact exceptional Object grants and
atomic API creation provenance; [Object scope](object-authority-scope.md).
- Transactional complete-binding snapshots for recursive Path changes and
all-alias Domain-local Object purges; [mutation integrity](path-mutation-integrity.md).
- Atomic controller manifest sequence allocation and managed snapshot,
inherited-permission and checkpoint application; authority collision and
unsigned-downgrade rejection; [manifest integrity](federation-manifest-integrity.md).
- Private, per-result City map/details/macros/badges, recomputed visible
portals/counts/relations, local generation Worker, cancellation/cache bounds,
directional keyboard navigation and immersive courtyards;
[navigation contract](city-worker-navigation.md).
- Persisted scheduler projections for PDF page counts and non-ZIP archive
metadata, localized pending/retry UI and immutable Revision entry links;
[projection cache](projection-metadata-cache.md).
- Bounded compact search with full Paths, matching-source badges and safe
excerpts/highlighting; [search contract](search-results.md).
- Bounded metadata-only Object/Revision APIs and paginated history, retaining
array response shapes and explicit continuation;
[Object pagination](object-list-pagination.md), [Revision pagination](revision-listing.md).
- Literal URL encoding in all three children views, including filenames with
question marks, fragments, percent signs and non-ASCII characters.
- One-connection-safe City read transactions with deadlines/ceilings and literal
boundary matching; [read integrity](city-read-integrity.md).
- Atomic bounded zombie selection/purge, current-Domain provenance for HTTP
administration, retained global maintenance grace and orphan-writer guards;
[GC integrity](zombie-gc-integrity.md).
These are not a claim that every endpoint, derived projection or write path has
finished authorization and concurrency review.
### 2026-09-23: user-space audience controls
- `/u/{username}/_/edit` now separates profile metadata, avatar, Wiki-root and
descendant audiences. Descendant exact/subtree overrides can only narrow the
default, are CAS-versioned/audited, and follow atomic Path rename.
- A dedicated anonymous live-head reader supplies user profile, Viewer/raw,
children, scoped Tree and Browser projections without adding `/u/` to global
anonymous navigation. It rechecks the Domain public ceiling per request and
rejects aliases and UUID/Revision bypasses.
- Authenticated listings and direct Object/Revision authorization also enforce
private user-space audiences. Owner and Domain-admin recovery are explicit.
Focused revocation, alias, navigation and recursive-rename tests pass. See
[user-space publication](user-space-publication.md).
## Remaining gates and risks
### P0: authority and content trust
1. Finish authorization-policy/version fencing inside every write transaction.
Recursive binding snapshots protect namespace races, not a concurrent
revocation of the grants themselves. Typed decoded mutation targets,
handler-method closure and idempotency remain wider cross-handler work.
2. Complete publication-impact review and mutation fencing on the implemented
owner/draft-policy and [inert HTML boundary](html-projection-trust.md). Keep public
enabling gated on structural mutation/alias fences and common anonymous-read
policy/revocation tests. See [ownership design](locality-publication-ownership.md).
Extend denial tests to each new projection; CSP is not an authorization grant.
3. Local-email ownership, explicit external-account linking, provider subject
migrations and administrator last-owner suspension/transfer need dedicated
lifecycle workflows. Rejecting ambiguous email matches is not email proof.
4. Domain-to-Domain PSK identity/group/grant inheritance needs its own origin,
replay, conflict and revocation contract. The completed Campus-admin local
projection is not that cross-instance synchronization feature.
5. Audit remaining list/projection, asset and adapter paths with
denial-focused tests before claiming complete Domain isolation. Legacy
unknown-origin unbound Objects require explicit grants or trusted recovery.
HTTP zombie GC is now provenance-scoped; trusted global maintenance remains
a distinct instance authority rather than a Domain administrator operation.
### P1: City correctness and responsiveness
See [City review and reconciliation](city-review-and-reconciliation.md).
CITY-A through CITY-D remain partially open. Remaining work includes shallow
Path/portal inference, deterministic generated Spot name collisions,
idempotent no-op application, explicit generated/manual ownership, exclusion
tombstones, event watermarks and a transactional mutation outbox.
Worker generation and bounded courtyard DOM do not solve connected/fair road
allocation or all main-thread topology/layout work. Lazy locality/Page
projections and a directory index remain important for much larger Wikis.
The Viewer sidebar / paginated navigation API is also separate from the
already-implemented home layouts and scoped Tree View.
### P1: projection and storage scaling
1. Non-ZIP entry extraction still runs a bounded foreground decoder. Durable
entry artifacts need quotas, leases, Range semantics and archive-bomb policy.
ZIP central-directory parsing and nested/compressed TAR expansion need their
own bounded worker/index contract.
2. Native decoders have input/output/thread/time bounds, not hard memory/cgroup
limits. A weighted scheduler resource budget and decoder isolation remain.
3. Search FTS still contains historical revisions; current-only indexing,
Japanese infix search and sanitized plain-text indexing are separate tasks.
SQL deadlines/candidate bounds limit work, not unlimited recall.
4. Browser/children/Tree and some link projections still aggregate large Path
sets. Request-scoped ACL removes repeated grant queries but does not replace
a directory index, bounded SQL candidates or fully opaque continuations.
5. Large-binary restore and several trusted full-list helpers still hydrate or
enumerate complete data. HTTP Object/Revision pagination does not silently
change explicit CLI full exports.
6. Remote Document Store backends, read-repair, retention proofs, cross-instance
job leases, dead-letter operations and writable metadata fencing remain.
### Operations and intentionally deferred high-risk work
- Existing deployment is two application instances with separate SQLite state,
not a shared-writer HA service. DR/LB require replication, fencing, key custody
and recovery drills; no live SQLite-over-network-filesystem shortcut.
- Enrollment tokens currently present in compose must be moved to a selected
secret mechanism and rotated deliberately. No credentials were automatically
replaced, printed or copied as part of these repairs.
- Untrusted plugin execution/native helpers remain disabled/deferred until the
runtime capability/signature/isolation model exists. vim.wasm runtime work
remains on the user's explicit hold.
- Live S3/SSHFS/WebDAV/MWDB/Karton/SNMP/LDAP integration requires selected endpoints,
credentials and test services. No external service was provisioned implicitly.
## Ordered next work
1. Add complete publication-impact previews and structural mutation/alias fences
to locality governance; keep anonymous access disabled until all publication
gates and fresh activation confirmations are satisfied.
2. Complete remaining mutation/policy transaction fences and account ownership
lifecycle; preserve denial tests and audited provenance.
3. Finish bounded/lazy City and directory projections; implement idempotent
URL inference with generated/manual ownership before automatic event-driven
application.
4. Add the transactional Domain activity outbox, verified actor attribution,
durable consumer watermarks and recent-edit projections.
5. Then add delegated shared links, notifications/inbox, moderated comments,
rankings/quality, diary calendar/recent entries/comments and resumable tDiary
import. Their detailed contracts remain in [System extensions](system-extensions.md).
6. External connectors, isolated third-party plugins and DR/LB/HA follow only
after their authority, retention and operations prerequisites are met.
## Verification expectations
Every hardening slice must run `go test ./...`, include a regression test for
the denied case, and update the relevant design document and roadmap checkbox.
Deployment validation must confirm both app nodes are healthy and that a
foreground request cannot expose another Domain's Object, Revision, Path, or
adapter workspace.
+61
View File
@@ -0,0 +1,61 @@
# アクティブ通知とWeb Push
更新:2026-09-25。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。実機Push受信確認は未実施。
## UIと設定
通知ベルを開いたInboxの「⚙ 通知設定」に集約する。アカウント・ドメイン・ブラウザごとにlocalStorageへ保存し、他ユーザの設定を継承しない。通知本文はlocalStorageに保存しない。
| 状態 | 動作 |
| --- | --- |
| フォーカス中 | 右下に8秒で消えるトースト。最大3個。入力フォーカスを奪わない。既定ON |
| 別タブ・別ウィンドウ/タブ終了 | 明示的に許可した端末へWeb Push。OSの通知UIを使用 |
| 再訪 | 前回訪問以降の未読がある場合、設定ONならInboxを自動表示。既定OFF |
| ダイアログ・入力を操作中 | 自動Inboxは保留し、次の確認時まで待つ |
新着は30件ずつ取得し、Inboxは「さらに表示」でページングする。訪問watermarkはサーバー時刻を使う。Web Locksと通知UUIDの短い履歴(最大200個)で複数タブのトーストを抑制する。Web Locks非対応時はbest effort。
音は「なし/ソフト/チャイム/ベル」と音量・試聴。Web Audioはブラウザの自動再生制限に従い、利用者の操作後に有効になる。カスタム音はフォーカス中のページ通知用。背景/タブ終了時の音はOS設定で決まり、サイト側から任意の音に置き換えることは保証しない。
ブラウザの通知許可は設定操作時のみ要求する。HTTPSと対応ブラウザが必要。iOS等はホーム画面への追加など端末側の条件もある。サービス・省電力・通信・キュー待ちに依存するため、定刻到達を保証するアラーム用途ではない。
## 配信経路と安全性
`notification_inbox`挿入のDB triggerで`notification_push_queue`へ原子的に追加する。Inboxの全種類(タスク期限・計画日、Pomodoro、アナウンス等)で同じ経路を使う。購読開始前の通知を一斉再送しない。
`/_/api/v1/notifications/push`:
- GET: VAPID公開鍵のみ。秘密鍵はDB内部に保存。
- POST: PushSubscription、focused、seen(最大30通知ID)。購読更新/閲覧中のack。
- DELETE: 現在の利用者が所有する購読を削除。
購読はDomain・Principal・**元の認証セッションのハッシュ**に束縛する。Bearer tokenは保存しない。配信時にセッション期限/失効、Principal、membership、Domain配置を再確認する。ログアウト後や無効化後は送信しない。最大8購読/利用者・Domain、30日lease(閲覧時に更新)。
VAPID秘密鍵は`notification_push_keys`に保存するため、DBバックアップを秘密情報として扱う。鍵を失った復旧では再購読が必要。端末の購読URL・鍵・通知本文をログへ出さない。
送信先はChrome/Chromium FCM、Mozilla Push、Apple Web Pushに限定。HTTPS/443のみ、資格情報・fragmentを拒否し、公開IPをDNS解決後に固定する。proxy環境変数とredirectは使用しない。プライベートIPへの接続は禁止する。Push本文は暗号化された通知UUID/受取人UUID/Domain UUIDのみ。件名・本文をPushサービスへ送らない。OSに表示するのも一般的な「新着通知」のみ。クリック後に通常の認可されたInboxで詳細を表示する。
Service Workerは`/static/js/notifications-worker.js`、scopeは`/static/js/`。fetch handlerやページキャッシュを持たず、既存のWikiページ/エディタに古い内容を返さない。notificationclickは同一originの`/v/notification`だけを開く。
## スケジューラと上限
イベント`notification.push.deliver`、定義`builtin.notification.push`。既定30秒、priority -3。設定画面のイベント設定から停止・間隔変更・手動実行でき、再起動で既存設定を上書きしない。
- 最大20件/run、全体25秒、送信要求5秒。DB transaction内でネットワーク通信しない。
- 60秒のclaim lease。期限切れを再取得できる。クラッシュ時はat-least-onceだが、ブラウザ通知tagを固定し積み上げない。
- 429/5xx/通信失敗は指数backoff、最大5試行。404/410は購読を削除。
- キューの有効期間24時間、Push側TTL300秒。期限切れキュー削除は最大500件/run、期限切れ購読削除は100件/run。
- フォーカスlease90秒。閲覧中は送信を延期し、ブラウザが一覧を受け取った通知のackでキューを消す。表示できなかったままタブが閉じればlease終了後に再評価する。
- 前面pollは30秒。Pushが有効な背景タブは定期pollを停止し、Pushと復帰を契機に更新する。
- sent/failed集計をイベントログへ記録。再送でもInbox本体は複製しない。
フォーカスを失う瞬間やネットワーク遅延にはraceがあり、OS通知を完全に抑制する保証はしない。常に通知権限とOSの設定が優先する。
## 検証・残TODO
- Go: 原子rollback、claim重複防止、focus延期とack、他人のack拒否、失効後の配信遮断、backoff、購読API認証、公開鍵のみ、送信先とP-256鍵検証、イベント設定保持。
- Chromiumの合成fixture: 前面トースト、再訪Inbox、設定モーダルの横幅、既存Inbox既読/バッジ。実通知サービスへは送っていない。
- TODO: 実機Chrome/Firefox/Safari/iOSでの購読・閉タブ配信・復帰・logoutを確認。Pushサービス障害テストの拡充、端末一覧/VAPID rotation UI、quiet hours/digest、種類別設定、OS通知の詳細表示opt-in、端末間の個人設定同期。
- TODO: expired/revoked購読の清掃メトリクス、Push queue深さ/遅延/失敗コードの管理UI。旧worker購読の移行手順。
参考:[MDN Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)、[MDN Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)、[webpush-go](https://github.com/SherClockHolmes/webpush-go)。
+43
View File
@@ -0,0 +1,43 @@
# 2. アドレス・保存・アセット
状態:基本モデルとローカル保存は実装済み。外部保存・保持管理の一部はTODO。
## アドレス表
| 内部指定 | 意味 | HTTP上の主な入口 |
| --- | --- | --- |
| `path:/manual/start` | ドメイン内の可変な住所 | `/manual/start` |
| `uuid:…` | Page/Objectの安定ID | `/o/uuid:…` |
| `rev:…` | 特定の不変Revision | `/r/view/…`、`/v/raw/rev:…` |
| `sha256:…` | 不変Document | `/_/obj/sha256:…` |
| `asset:image:logo` | ドメイン内の編集用HEAD | 管理者向け `/v/raw/asset:image:logo` |
通常エディタの正規入口は `/e/-/{path}`。従来の `/e/{path}` は互換入口です。生データは `/v/raw/path:/…` 等を使い、通常Pathと紛らわしい `/raw/` を増設しません。別ドメインへのリンクは宛先FQDNを含む絶対URLです。
## 保存トランザクション
1. 言語・MIME・保存対象と現在の書き込み権限を検証する。
2. 内容のSHA-256を計算し、`documents/sha256/` に不変Documentを永続化する。
3. Page、Revision、必要なPathと依存参照を確定する。
4. 派生処理へ通知する。共通outboxの全書き込み接続は後続課題。
Documentを先に書くため、DBのrollbackで未参照blobが残る可能性はあります。逆に、DBだけ確定して正本バイト列が存在しない状態は許しません。SQLiteのbody列は移行互換用で、Document Storeと二つの正本を作りません。
## アセットの可変HEADと固定参照
Asset名は `(domain_uuid, asset address)` で一意です。HEAD変更は旧Documentを上書きしません。HTML保存時に `asset:` を解決し、表示用参照をSHA-256へ固定します。編集用の由来は別属性で残し、次回保存時にHEADを再解決します。
`revision_document_refs` が依存Documentを記録します。過去Revisionの閲覧で最新HEADへ追従しないことが再現性の条件です。CLIと管理画面ではHEADを扱えますが、公開ページの依存物を自動公開する根拠にはなりません。
## 認可・条件付き操作
ハッシュURLは現在のDomainで読めるPageや許可された管理操作との関係を検証します。ETagと `X-PagesWiki-Object-UUID`、`X-PagesWiki-Revision-UUID`、`X-PagesWiki-Document-SHA256` は識別情報であり資格情報ではありません。
Asset更新は条件付き更新を使います。ただし同じ内容でMIME等だけ変わる競合には、HEADハッシュとは別の状態versionを導入する設計が必要です。
## TODO
- 保持期限・削除プレビュー・export中の保護を統合したDocument GC。
- Assetの状態version、共通監査outbox、依存関係込みの公開レビュー。
- 大容量復元のストリーミング、外部Document backend、破損検出とread-repair。
- CLIの全書き込みとWebの正本保存契約の統一。CLIは現在も信頼されたローカル管理経路で、HTTP認可を迂回する点を明示する。
+59
View File
@@ -0,0 +1,59 @@
# 5. 認証・グループ・権限
状態:パスワード・TOTP・セッション、OIDC、LDAP、SMTPリンク、グループと主要な認可経路は実装済み。全経路の監査完了を意味しません。
## 認証から認可へ
認証器はPrincipal identityを証明します。その後、Domain membership、グループ・Role、対象操作のcapability、上位Localityの制限を評価します。OIDCのclaimやメールアドレスだけで管理権限を付与しません。
Principalにはactive / readonly / suspended / quarantinedの状態があります。membershipや状態の失効は次の要求で反映します。
LDAPはドメイン単位で設定します。検索用アカウントで`{{username}}`を
RFC 4515エスケープして一意なエントリを取得し、そのエントリのユーザーDNで
再bindできた場合だけ認証成功です。初回だけローカルの一意なユーザー名または
メールアドレスへ連結でき、その後は`entryUUID`やActive Directoryの
`objectGUID`など、設定した不変属性とprovider UUIDの組で識別します。DN、表示名、
メールアドレスを継続ログインの識別子にはしません。自動作成は任意で、作成時は
ローカルパスワードを持たない通常のmemberに限定します。
LDAP/LDAPS、StartTLS、証明書検証、追加CA PEM、検索Base DNとfilter、属性mapping、
既存アカウントの照合項目、保存済み設定によるログインテストを管理画面から設定
できます。bindパスワードは暗号化し、利用者パスワードは保存・ログ出力しません。
LDAPグループをPagesWikiのグループや権限へ同期する処理は認証と分離し、明示的な
mappingだけを適用する後続タスクです。
## セッションの目的を分離する
ブラウザはHttpOnlyのホスト限定Cookie、APIは明示的なBearer credentialを扱います。現行はブラウザ用とAPI用のトークン種別を分け、相互に流用しません。「全画面でlocalStorageへBearerを置く」構成にはしていません。
adapter、federation、認証challenge、将来のshareはそれぞれ別の検証系です。明示された無効なAuthorizationをCookieで救済しません。Cookie経由の変更には同一origin検証、ログアウトにはPOSTを使います。
OIDCはissuer・署名・claim・state/nonce/PKCE・browser bindingを検査します。SMTPリンクは短命・一回限りのchallengeで、配送遅延をログイン要求に持ち込みません。メール一致とメール所有の証明、外部identityの明示的な連結は引き続き整理が必要です。
## 権限プロファイル
| 表示用プロファイル | 許可する内容 | 許可しない内容 |
| --- | --- | --- |
| read | 閲覧 | 全変更 |
| read/write once | 未存在の対象の新規作成・アップロード、閲覧 | 上書き、再編集、削除 |
| read/write | 閲覧・作成・更新・rename・link | deleteの暗黙付与 |
| upload only | 指定範囲の未存在対象へアップロード | 一覧、閲覧、上書き、削除 |
| group admin / user | グループ内の管理上の役割 | それだけを根拠にした本文権限 |
削除は独立したgrantです。新規作成・uploadの可否は正規化後の最終Pathをトランザクション内で検査します。Pathを先に調べ、後で無条件上書きする実装は禁止です。
## 管理グループと所有者
`campus_admin` はキャンパスとドメイン配置、`domain_admin` はDomain設定・アカウント・グループを管理するビルトイングループです。普通のグループ管理者がこれらを自分へ付与できてはいけません。
Quartier・Spotのco-ownerは公開設定等の委譲された管理者です。所有者であることと、上位が許可していない公開を広げることは別です。
## TODO
- 全変更経路で認可versionと更新対象を同一トランザクションに固定する。
- 最後の管理者の停止・移管、メール所有、外部identity連結・解除。
- OIDC/LDAP外部グループの明示mapping、由来を保持した同期・失効・監査。
- 説明可能な権限総覧:付与元、継承、上位制限、対象操作、失効理由を表示する。
- PSK継承、adapter、Asset等を含む拒否・競合・再送テストの拡充。
個人用 `/u/{username}`、グループ用 `/g/{groupname}` は本文領域と `/_/edit` 等の管理領域を区別します。プロフィール画像変更を本文の無制限履歴と混同しません。ユーザー領域の所有者はプロフィール情報・画像・Wiki root・配下のaudienceを個別に狭められます。`private` は通常のDomain read grantより優先し、所有者と復旧権限を持つDomain管理者だけが読めます。匿名公開はDomainのpublic上限を越えられません。
+35
View File
@@ -0,0 +1,35 @@
# 10. ブログ・日記・公開ドメイン射影
状態:投稿・登録・カレンダー・同一インスタンス射影・公開記事・RSSは実装済み。コメント、tDiary移行、遠隔射影はTODO。
## 記事の実体とURL
ブログと日記は別のシステム拡張ですが、本文は通常Page/Revisionです。Domainごとのprefixに対し `{prefix}/yyyy/mm/dd`、任意keywordがあれば `{prefix}/yyyy/mm/dd/{keyword}` へ作成します。同日複数記事が可能です。
日付・著者・カテゴリ等はPage UUIDに紐づく記事メタデータです。Path変更で失わず、登録解除でPage本文は消しません。日付はcivil dateで、timezone変更時に過去の記事を勝手に別日へ移しません。
## 表示と投稿
月別は `/v/blog/yyyy/mm`、日別は `/v/blog/yyyy/mm/dd`。日記も同様です。`?own` とカテゴリを日付移動で維持します。`/v/blog` は全期間、日記の入口は当月が基本です。日付の旧query入口は正規Pathへ案内します。
タイトル下は日付とタイトルのコンパクトな一覧、月入力・適用・リセットはカレンダー上の一行です。大量記事では読みやすさとページ送りを優先します。
`/v/blog/-/new` と `/v/diary/-/new` は認証された投稿画面です。Page、Path、Revision、記事情報、journal、再送receiptを原子的に作成します。既存Pathは409、同じrequest_idの再送は重複作成せず返します。入力変更後の同じID流用も409です。
## 専用ドメインはコピーではなく射影
例:元ドメインの `/blog` を `blog.pages.anya.jp/` に表示します。現行は同一Campus・同一インスタンスに限ります。編集は元ドメイン、表示の名称・テーマは表示先ドメイン、専用記事リンクは `/yyyy/mm/dd[/keyword]` です。
元が非公開なら、射影の設定だけで公開しません。匿名一覧・月件数・記事本文は承認済みまたは自動公開条件を満たす内容に限定します。登録タイトルはPage公開を継承しますが、他の登録メタデータまで無条件に公開しません。設定不整合で別の内容へ黙ってfallbackしません。
## RSSとX
専用ドメインの `/rss.xml` は最新20記事を配信し、`content:encoded` に安全化したHTMLを含めます。リンクを絶対URLへ直し、正確な公開状態を再検査します。1記事1 MiB入力、合計8 MiB、5秒の生成制限を持ちます。
投稿後のXシェアはWeb Intentをユーザーが押す方式です。設定された専用ドメインのURLを選び、未公開なら警告します。投稿完了、公開完了、X投稿完了を同じ状態にしません。既にRSS等へ複製された本文は撤回できません。
## TODO
遠隔記事射影の署名・取得・失効、metadata公開範囲、Atom、keyset paging、outbox接続、receipt/孤立データ保持、予約公開、コメント・最近のコメント、tDiary import。
tDiaryは対応版・入力形式をfixtureで固定し、Ruby/eval/Marshalを実行して取り込む方法は使いません。旧URL、セクション、添付、コメント著者の出典を保持し、重複・部分失敗から再開できる取り込みを設計します。
+70
View File
@@ -0,0 +1,70 @@
# 予定・タスク共通CalDAV接続
2026-09-27追記:`organizer.tasks 0.10.0`で[MKCALENDARによるVTODOリスト作成](caldav-task-lists.md)を追加。共通直下のUUIDはVEVENTまたはVTODOリストを表し、種別でハンドラを選ぶ。予定本文の読み込みで判定しない。
2026-09-26実装。`organizer.calendar 0.2.0`/`organizer.tasks 0.9.0`。01:33 JSTに本番両インスタンスへ反映済み。[反映・検証記録](../../operations/deployments/2026-09-26-common-caldav.md)。
2026-09-27追記:[OneTask向け互換モード](caldav-onetask-compatibility.md)を実装、10:01 JSTに本番反映。通常は引き続き`calendar-access`を宣言せず、明示ONで発行した資格情報のみ接続判定互換のため宣言する。完全なRFC準拠ではない。実機の同期完了は未確認。
## 1. 接続と認証
共通接続先は `/_/api/v1/caldav/`。slash有無ともリダイレクトせずPROPFINDを処理する。rootはcurrent-user-principal/principal-URL/calendar-home-setを返す。Depth 1は許可された予定カレンダー(VEVENT)と個人タスクコレクション(VTODO)を返す。予定とタスクを同じICSリソースに混在させない。
| 対象 | URI |
| --- | --- |
| 共通home/principal | `/_/api/v1/caldav/` |
| 予定 | `/_/api/v1/caldav/{calendarUUID}/` |
| 個人タスク | `/_/api/v1/caldav/tasks/default/` |
| 既存タスク専用home(維持) | `/_/api/v1/caldav/tasks/` |
| 接続資格情報の発行/一覧 | `POST/GET /_/api/v1/caldav-credentials` |
| 失効 | `DELETE /_/api/v1/caldav-credentials/{id}` |
予定/タスク両画面の⇄ボタンから共通設定を開く。発行時に対象 `tasks`(タスクのみ)、`calendar`(予定のみ)、`all`(両方)とread/write、有効期間を明示選択する。初期選択は開いた画面の対象で、両方を自動付与しない。
Basicのユーザー名は資格情報ID、パスワードは発行時のみ表示するランダム値。従来と同様、秘密値はSHA-256のみ保存し、閉じたダイアログからも消去する。通常ログインセッションでのみ発行/失効できる。DAV資格情報をWikiやJSON APIのログインとして利用することはできない(匿名公開APIを非ログイン扱いで参照できることとは別)。HTTPSを使う。
既存の資格情報と旧管理APIは維持。`organizer_dav_scopes`に対応行がない資格情報は必ず`tasks`として扱う。既存資格情報を予定アクセス付きに更新するAPIは設けず、新規発行と旧資格情報の明示失効で切り替える。新規の予定/共通秘密値は`pw_dav_`、既存互換タスク秘密値は`pw_taskdav_`。古いバイナリは`pw_dav_`を拒否するため、切り戻し時にも予定限定資格情報がタスク権限へ化けない。
## 2. 認可
- 資格情報をドメイン/所有者/期限/失効状態に結び、principalとdomain membershipの状態も確認する。
- Scopeは対象種別の上限であり、他人のカレンダーを共有する権限ではない。既存のカレンダーowner/member/publicポリシーを別途適用する。
- 共通homeの探索結果はscopeと有効な拡張機能で絞る。片方の拡張が無効でも、他方の接続設定・探索は動く。
- 予定の書き込みは資格情報のwrite許可、active状態、カレンダーのCanWriteを全て必要とする。外部ソース由来カレンダーは従来通り書き込み不可。
- 予定変更時はカレンダーmetadata lock内でACLと資格情報の失効・期限・write・scopeを再確認する。タスクは既存のDB transaction内再確認を維持する。
- API・DAV応答はprivate/no-store。通常の匿名公開予定の読取経路は維持し、無効なBasic資格情報を匿名扱いにフォールバックしない。
## 3. 予定のresource名と正本
Web作成分は従来の`base64url(UID).ics`を維持。CLIが作成する任意の安全なASCIIファイル名(英数字・`.`・`_`・`-`、末尾`.ics`、最大700 bytes)を受理する。UIDとファイル名は別の識別子。
CLI由来のUID→filenameは`calendar.json`の`dav_names`として保持する。新規resource予約と月別ICSを同じmanifest置換でcommitする。DBだけのaliasにはせず、索引再構築・カレンダー設定変更でも保持する。削除時は対応aliasも削除する。同じcalendar内のUID重複、filename衝突、既存UIDの差替えを拒否する。
既存のWeb用canonical URLも引き続き解決する。WebビューアはfilenameをUIDとしてbase64 decodeする前提を廃止し、既存JSONイベントAPIの`?resource={filename}`でサーバー側解決する。`?uid=`も維持。ETag一致時には本文を取り直さない。
新規PUTは`If-None-Match: *`を推奨するが、chroncal互換で完全な新規identityに限り条件なし作成も可能。既存更新にはIf-Match(未指定428、不一致412)を必須とし、並行作成でも上書きしない。DELETEは予定の削除、タスクのアーカイブという既存の意味を維持する。
## 4. 取得上限と互換性
- 従来のtime-range付きREPORTとETagを利用したWeb表示を維持する。
- 初回同期用の全件calendar-query(VCALENDAR全体、またはVEVENT指定)を追加。metadata lock内で完全なsnapshotを取得し、最大10,000 resource/32 MiBを超えれば507で全体を失敗させる。黙った切り捨てはしない。
- PROPFIND Depth 1による予定resource列挙、全項目calendar-data選択にも対応。無制限Depth、部分projection、未対応filterは拒否する。
- 1 resource上限256 KiB、multigetは200 href、DAVリクエストは20秒上限。既存のtime-range上限370日も維持する。
- sync-collection/sync-tokenは未対応。405を返し、chroncalはcalendar-queryへフォールバックする。完全なCalDAV適合を示すcalendar-accessは広告しない。
- 新規予定のiCalendar対応範囲は従来のまま:単独VEVENT、UTC DATE-TIMEまたはDATE。TZID/VTIMEZONE、浮動時刻、繰り返し、VALARMは書き込み未対応。chroncalの`--timezone`で出力されるVTIMEZONEも拒否する。情報を黙って欠落させる変換はしない。
## 5. 検証と運用
隔離したfixture、HOME、XDG、DB、資格情報のみでchroncal 0.10.0の共通探索、予定とタスクの取得、予定作成/CLI編集/Web変更取得/削除、タスク作成/完了/Web変更取得/アーカイブを検証。vdirsyncer/Todomanの既存タスク回帰も実施する。
権限scope、旧資格情報の移行既定値、read-only、失効、アカウント停止、拡張無効化、既存上書き拒否、並行作成、ACL取消、DB索引再構築、取得上限、Webのresource解決を試験する。ブラウザでは予定・タスク両方の設定UI、発行/失効/秘密値消去と、CLI filenameの予定描画を確認する。
本番の外部取り込みカレンダーの本文を調査・試験に利用しない。反映確認はhealth、未認証の経路、静的資産、エラーログ件数に限定する。
## 6. 後続TODO・切り戻し
- [ ] losslessなTZID/VTIMEZONE、繰り返し・例外、アラームのDAV書込契約。正本を拡張する際は外部ICS取り込みの投影と混同しない。
- [ ] sync-token/tombstone/変更journalによる大規模差分同期。
- [ ] 資格情報ごとのcalendar ID制限、カレンダー作成・属性変更のDAV対応。
- [ ] macOS/iOS等のGUI CalDAVクライアント実機検証。
- 旧バイナリは追加DB表を無視できるが、calendar manifestを更新すると未知の`dav_names`を失う。**CLIで予定を作成した後は、旧バイナリでカレンダーを編集しない**。緊急切り戻しではカレンダー拡張を無効化して修正版を待つか、整合したDBと正本のバックアップ復元を別途承認の上で行う。DBのみ復元し正本を過去に戻したつもりにしない。
@@ -0,0 +1,34 @@
# DAVx⁵/Tasks.orgの互換性調査
2026-09-27。利用者指定の公開ソース`bitfireAT/davx5-ose`を読み、commit `167dc85f211119db6a98596c08f64e5df32ca679`(2026-09-25)を基準に確認。インストール済みアプリのバージョンとは同一と仮定しない。Android実機でDAVx⁵を実行した検証ではない。
## 同期方式
- `core/src/main/kotlin/at/bitfire/davdroid/sync/TasksSyncManager.kt`:タスクは`PROPFIND_REPORT`固定。
- `resource/remote/BaseWebDavCollection.kt`:Depth 0のPROPFINDでsupported-report-set、sync-token、getctag等を取得する。
- `resource/remote/ResponseExt.kt`:sync-tokenを優先し、なければgetctagを使う。両方なければnull。
- `sync/SyncManager.kt`のsyncRequired:状態nullは「同期必要」と判断する。両方ないこと自体で同期を拒否しない。
- `sync/TaskSyncer.kt`と`resource/remote/CalDavCollection.kt`:VTODOのcalendar-queryを送り、ETagで比較し、必要なリソースをcalendar-multigetする。タスクqueryにtime-rangeは指定していない。
- カレンダーは、期間制限やsync-collection未対応の場合PROPFIND_REPORTを選ぶ。未対応のsync-collectionを広告してはいけない。
したがって、提示された`XTaskApp / CodeSpark / SyncTaskListsSend`の「sync-token or ctag必須」というエラーは、調査したDAVx⁵の同期コードの挙動とは異なる。端末上でどのアプリが直接CalDAV接続しているかを区別する必要がある。
## PagesWikiとの差分と残件
- 既存リストの単純VTODO同期に必要なREPORT、ETag、multigetは既存実装にある。実機確認は未完了。
- DAVx⁵のリスト新規作成は`DavCollectionRepository.generateMkColXml`でDAV:resourcetypeを常に付ける。現在のPagesWikiの限定MKCALENDARはこれを未対応propertyとして拒否する。VTODO専用で正しいresourcetypeを受理する回帰試験と実装が必要。
- 作成時には説明・色・タイムゾーンや複数component-setも付く場合がある。受理する項目は正本保存・PROPFIND往復まで設計し、未知の意味を黙って破棄しない。
- 時刻付きVTODO、繰り返し、VALARMはPagesWikiの現行限定プロファイルでは未対応。DAVx⁵が生成できる全タスク形式に対応済みではない。
- リストの削除/属性編集、差分sync-tokenも別途残件。
## 今回の状態
追加途中だったctagのローカル変更(追加表・更新フック・応答property)は利用者の指示を受け取り下げた。本番には反映していない。取り下げ後の名前付きリスト・認可・原子性テストは成功。本番は0.10.0のまま。
利用者はTasks.orgを試す予定。DAVx⁵経由ではDAVx⁵のタスクアプリにTasksを選択し、同期対象の既存リストを有効化する。同じアカウントをTasks.org側に直接CalDAVとしても追加すると、Tasks.orgはDAVx⁵データを無視するため二重設定に注意する。初回は件名・日付だけのタスクで両方向を確認し、複雑な形式は分ける。
## 参照
- [調査対象の固定commit](https://github.com/bitfireAT/davx5-ose/tree/167dc85f211119db6a98596c08f64e5df32ca679)
- [Tasks.org公式:DAVx⁵連携](https://tasks.org/docs/sync_davx5/)
- [DAVx⁵公式:タスク連携](https://manual.davx5.com/tasks_notes.html)
@@ -0,0 +1,73 @@
# OneTaskのcalendar-access判定への互換対応
最新追記:利用者のスタックトレースにより`SyncTaskListsSend → CreateCalendar → MKCALENDAR`のVTODOリスト新規作成失敗と特定した。[複数タスクリスト実装](caldav-task-lists.md)で対応する。以下の「MKCALENDAR未対応」は0.9系時点の調査記録。0.10.0で明示的なVTODOリスト作成を追加するが、全機能のRFC準拠は引き続き宣言しない。
## 2026-09-27 接続診断の追記
利用者のcurl応答で、共通入口の認証済みOPTIONSが204、`DAV: 1, calendar-access`、`X-PagesWiki-CalDAV-Profile: limited-compatibility`となることを確認した。資格情報の再発行を繰り返す段階ではない。別アプリOneCalendarでの追加成功に続いて、**OneTask側も追加できたと利用者から確認された**。追加順序によるものか再試行によるものかは未確定であり、カレンダーを先に追加することを必須手順にしない。アカウント追加とVTODOの同期・更新成功は分けて扱う。
従来のアクセスログにはHTTPステータスがなく、10:13 JST頃の共通入口PROPFINDが成功したか判定できなかった。CalDAV経路だけ、次の固定分類による診断ログへ置き換える。
- method、target(home/task_home/task_collection/task_resource/calendar_collection/calendar_resource/well_known)、status、duration、request_id。
- auth(none/basic/malformed_basic/bearer/other/multiple)、outcome(未判定・Basic成功/拒否・session成功・匿名・欠落・不正・複数Authorization)。
- challengeの有無、限定互換宣言の有無。
- 資格情報ID・ユーザ名・秘密値・Authorization値・Cookie・User-Agent・リソース名・query・XML/ICS本文は出力しない。認証拒否の詳細な秘密値照合結果も公開しない。
認証・ACL・プロトコル応答は変更しない。401なら認証、403なら権限/未対応要求、207ならクライアントの探索解釈を切り分ける。ただし207でも個別propstatは404になり得るため、207だけで必要プロパティが全て成功したと判断しない。認証省略や権限緩和で迂回しない。外部取り込み予定にはアクセスせず、実データ本文なしのログと隔離fixtureで調査を継続する。
診断ログ追加は10:16〜10:17 JSTにapp/app2へ反映。認証済み共通入口PROPFINDの207を確認。MKCALENDARの404も観測したが、実行アプリはログから特定できない。外部クライアントからのコレクション新規作成は未対応であり、既存タスクの作成・更新とは別課題として残す。未実装のMKCALENDARを成功扱いしない。
その後「追加はできたが、タスクの中身が見えず`calendar or event not found`」との報告。10:17:27のMKCALENDAR404と同じ文言を既存カレンダーハンドラが返す。10:18:28にはtask_collectionへのPROPFIND207/basic_acceptedも観測。現在のログにタスク本文取得のREPORT/GET失敗はなく、一覧表示の不具合とMKCALENDAR未対応の関係は未確定。「PagesWiki Tasks」が見えるか、エラーが同期時かリスト新規作成時かを利用者へ確認中。未対応メソッドを存在確認より前で拒否して誤解を招く404を避けること、VTODO探索の階層とクライアント相互運用を検証することを残件とする。接続成功のみで同期解決済みにしない。
2026-09-27実装、10:01 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-onetask.md)。**OneTaskアカウント追加は利用者確認済み。ただしタスク表示は未解決。互換ONで発行した資格情報が必要。**
## 原因と今回の境界
OneTaskはOPTIONS応答に`calendar-access`がない場合、`This CalDav server does not support calendar-access`として探索を停止する。従来のPagesWikiは限定的なCalDAV実装のため`DAV: 1`のみを返していた。これは認証失敗やPROPFINDの失敗ではない。
[RFC 4791 §5.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.1)では`calendar-access`は全MUST要件への対応宣言である。現在のPagesWikiはその全てを実装していない。従って本変更は**RFC完全準拠への変更ではなく、利用者が明示的に選ぶ接続判定の互換モード**である。付加的な独自ヘッダでこのRFC上の意味を変えられるわけではない。通常モードは今まで通り宣言しない。
## 設定と保存
カレンダー/タスクの⇄設定で認証情報を発行するとき、「OneTask互換モード(calendar-accessを宣言)」を選ぶ。初期値はOFF。限定実装と未対応機能を同じ画面に明示し、一覧にもOneTask互換と表示する。
管理API `POST /_/api/v1/caldav-credentials` の追加フィールド:
```json
{"label":"Android OneTask","scope":"tasks","write":true,"days":90,"calendar_access_compat":true}
```
従来APIも同じフィールドを受理する。scope(対象)とwrite(権限)は別のまま。互換設定で予定への権限や書き込み権限を追加しない。既存認証情報は自動変更しない。公開してしまった秘密値を再利用せず、旧認証情報を失効して新規発行する。
DBには`organizer_dav_compat(credential_id)`を追加。発行と互換フラグを同じtransactionで保存し、資格情報削除triggerで関連行を削除する。secret自体は従来どおりhashのみ。通常のログインセッション以外で発行できない。
## 応答
認証成功後、対象domain/owner/資格情報ID/有効期限に対応する互換行がある場合のみ、共通home・task home・task collection/resource・calendar collection/resourceで以下を返す。
```http
DAV: 1, calendar-access
X-PagesWiki-CalDAV-Profile: limited-compatibility
```
既存資格情報・互換OFF・Bearer/Cookieセッション・匿名要求は通常のまま。User-Agentから推測して勝手に互換設定を有効にしない。DB確認エラー時は通常応答に倒す。認証・scope・期限の失敗は401のままであり、失敗を成功応答に偽装しない。
OPTIONSの204は維持。Allowには実装しているメソッドのみを示し、MKCALENDAR・calendar-schedule・sync-token等を追加宣言しない。task collectionのPROPFINDにはcurrent-user-privilege-setとcurrent-user-principalを追加し、読み取り専用をwriteとして返さない。
## データと検証
未対応のTZID/日時付きVTODO期限/繰り返し/VALARM/部分projectionやfilterは引き続き明示的に拒否する。互換設定はこれらを変換・削除して保存を通す機能ではない。ETag必須の既存更新とACLも維持する。
`TestDAVCalendarAccessCompatibility`は報告されたOPTIONSの判定を再現し、その後の探索・取得・更新・削除、通常モード維持、User-Agent偽装無効、read-only、scope、失効・期限、管理API隔離、未対応繰り返し拒否を確認する。これはOneTaskアプリ自体の実行試験ではない。
chroncalの共通接続fixtureは互換ONで、旧タスク接続とvdirsyncer/Todomanは通常モードで回帰試験する。Chromiumでは設定の初期OFF、明示ON発行、一覧反映、失効、秘密値消去、タスク画面4サイズを確認する。すべて隔離された合成データを用い、本番資格情報・外部カレンダー本文は使わない。
2026-09-27の結果:全Goテスト成功。chroncal 0.10.0/vdirsyncer実行fixture成功。`TestCalendarChromiumSmoke`と`TestTasksChromium`(1440/1024/390/320幅)成功。JS構文・`git diff --check`成功。本番へのデプロイ、認証情報の発行・失効はこの作業では行っていない。
## 運用・残件
- [x] 本番への反映(2026-09-27 10:01 JST)。DBは追加表とtriggerのみで破壊的変更なし。旧バイナリは互換設定を無視するため、切り戻すとOneTaskの接続判定は再び失敗する。
- [x] OneTask実機でアカウント追加(利用者報告)。
- [ ] OneTask実機で一覧表示・作成・完了・変更・削除を確認する。一覧表示に問題報告があり、接続成功を全操作成功と扱わない。
- [ ] 実機で次の要求が失敗する場合は、Authorization・本文を除去したメソッド、対象経路、status、画面エラーを基に限定fixtureを追加する。
- [ ] 完全なRFC対応を目指す作業は共通CalDAVの残件(時間帯・繰り返し・filter等)として別途継続する。
+53
View File
@@ -0,0 +1,53 @@
# CalDAVタスクリスト作成とプロジェクト同期
**後続仕様**:0.11.0で通常プロジェクトも個別リストへ統一し、条件なし上書きを受理する。以下は0.10.0の記録。[新しい契約・移行と競合通知TODO](task-dav-project-unification.md)を参照。
2026-09-27。`organizer.tasks 0.10.0`。OneTaskの`SyncTaskListsSend`が`MKCALENDAR`でVTODOリストを作成する実例に対応する。認証エラーではなく、旧実装が未知のリストUUIDをVEVENTカレンダーとして検索し404にしたことが原因。従来の固定リストと認証・ETag・権限を維持し、成功応答だけを偽装しない。
10:44〜10:45 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-task-lists.md)。OneTask実機での再同期確認は利用者待ち。
## 1. 正本とURI
- `MKCALENDAR /_/api/v1/caldav/{UUID}/`でVTODO専用リストを作成する。要求URIをそのまま維持し、別URIへのリダイレクトは行わない。
- 1リストを1つの個人プロジェクトに対応付ける。表示名はプロジェクトのTitle、所属タスクはProjectUUIDで決まる。外部作成分はWebでも同じプロジェクトとして管理できる。
- URIのUUIDとプロジェクトのUUIDは別の識別子。正本プロジェクトの`dav_collection`にURIのUUIDを保存し、通常の版・CAS文書・変更journalを使用する。
- DBの`organizer_dav_collections`はdomain/pathの一意性・routing索引。プロジェクト正本の情報から再構築できる。通常JSON APIから`dav_collection`を注入・変更できない。
- 従来の`/_/api/v1/caldav/tasks/default/`は維持。DAV専用リストを持つプロジェクトのタスクだけを除外し、それ以外の既存タスク・通常プロジェクトは引き続きここに表示する。既存プロジェクトを勝手に外部リスト化しない。
- 名前付きリスト内のリソースは`/_/api/v1/caldav/{UUID}/{filename}.ics`。Webで所属プロジェクトを変更すると、元のリストから消え、移動先に同じUID/filenameで現れる。これはCalDAV MOVE対応ではない。
- 共通homeおよび旧task homeの探索で、利用者自身の有効な名前付きリストを返す。タスク拡張だけが有効な場合も使える。
## 2. 作成契約
[RFC 4791 §5.3.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.3.1)に従い、作成は一括成功か全拒否とする。対応範囲は明示的なVTODO component-setとdisplayname。VEVENT/混在/未対応property/不正XMLを黙って無視しない。
- UTF-8 XML、application/xmlまたはtext/xml。64 KiB、既存XMLの深さ・要素数制限を適用。
- component-setはVTODOのみを必須とする。displayname省略時はURI末尾を用いる。表示名の長さ等は既存プロジェクト検証を適用。
- 作成成功201+Location、private/no-cache/no-store。既存URIへの再作成は405+DAV:resource-must-be-null。再送で別プロジェクトを増殖させない。
- domain/pathは他利用者分も含めて一意。既存VEVENTカレンダーのディレクトリを上書きしない(存在だけ検査し、予定本文は読まない)。
- 1利用者・1ドメインにつき最大256リスト。上限超過507。削除済みとしてURIを再利用する契約はまだ設けない。
- タスクscopeまたはall、write権限、active membership/principal、拡張有効状態を検証。作成transaction内でも資格情報の失効・期限・権限を再確認する。
- 匿名作成・匿名リスト閲覧は不可。他利用者のリストは404、カレンダーだけの資格情報はタスクへ使えない。
## 3. タスク同期
PROPFIND/calendar-query/calendar-multiget/GET/HEAD/PUT/DELETEを既存実装と共通化し、リストごとに完全なsnapshotを返す。別リストのhrefをmultigetに混ぜても個別404にする。
UIDとfilenameの一意性はリスト内。異なるリストでは同名・同UIDを許可する。DB検索索引のみ、正本上のUIDでは許可しないNULを区切りにプロジェクトUUIDを付与し、既定リストの任意UIDと衝突しないようにする。外部ICSや返却URLに索引用の接頭辞は出さない。
Web編集時もプロジェクトのリストidentityとタスクのDAVメタデータを保持する。既存更新はETagとversion CAS、DELETEはタスクのアーカイブ。write transaction内で所属リストを再確認する。リストをアーカイブした場合、タスクを既定リストへ漏らさず、DAV上ではそのリストを非表示にする。
## 4. 検証
- OneTaskの提供したMKCALENDARのXML形状を合成fixtureで再現。201→探索→PUT→GET→REPORT→完了→Web変更→削除。
- 二つのリストの同UID/filename、相互混入防止、multigetの範囲制限、Web所属変更、索引再構築。
- 他利用者、read-only、calendar-only、匿名、拡張無効、VEVENT URI衝突、並行二重作成、失敗時にプロジェクトを残さないこと。
- chroncalの名前付きリスト往復同期。旧固定リスト・共通VEVENT接続・vdirsyncer/Todomanの回帰。
- Webタスク/カレンダー画面のブラウザ回帰。実機OneTaskでの最終同期確認は利用者の再試行で行う。
- 本番の資格情報・タスク・外部取り込み予定をfixtureに使用しない。観測は秘匿済みログとhealthに限定する。
## 5. 残件と切戻し
- リストのPROPPATCHによる名称・色変更、リストDELETE、DAV MOVEは未対応。リスト名はWebのプロジェクトで変更可能。リストDELETEを全タスク削除として仮実装しない。
- DTSTART/DUEの時刻、TZID、繰り返し、VALARM、複雑filterは従来の限定VTODO契約を維持。sync-tokenによる差分同期も別件。
- OneTaskが追加のproperty・filter・日時形式を送る場合は実要求に基づき、情報を落とさない形で対応を追加する。アカウント追加成功やCLI試験だけでOneTaskの全操作成功とはしない。
- **名前付きリスト作成後、0.9系の旧バイナリでプロジェクト/タスクを編集しない。** 未知のdav_collectionが失われたり、旧既定リストへ混入し得る。緊急切戻しはタスク拡張を停止してから行う。DBだけの無断巻戻しでユーザーの新規タスクを消さない。
@@ -0,0 +1,15 @@
# カレンダー・Cityのジョブ障害是正(2026-09-22)
## City
URL自動生成はSpot名をPathの同じ深さから作るが、Spot名の一意制約はStreet内ではなくDomain全体だった。別Streetで同名のSpotやundefinedを生成するとreconcileが失敗し、outboxが未完了のまま再試行されていた。
Pathによる既存要素の再利用を優先し、新規作成時に名前が衝突する場合のみPath由来の安定hashを識別名に追加する。表示タイトルは維持する。別Pathの要素を名前だけでマージしない。QuartierとStreetの正規化名衝突も同じ方法で回避する。再実行で要素が増殖しないことを合成データで検証する。
残タスク:手動作成との同時実行競合のリトライ、繰り返し失敗の再投入backoffと警告集約。過去の失敗ログは成功へ改竄しない。
## 外部カレンダー接続
DNS検証後に先頭IPだけへ接続していたため、その経路が利用できない場合に失敗した。他の検証済みIPへ再試行し、DNS/TLS証明書/タイムアウト/安全制限をURLやトークンなしで分類する。localhostとprivate IP直指定は設定段階でも拒否する。
Outlookへの実接続・予定内容の調査は行わない。ユーザー指定により、以降の検証は合成データのみとし、取り込まれた外部予定にはアクセスしない。一般的なOutlookフィードのTZID、有限RRULE、EXDATE/RDATE、移動・取消を含むRECURRENCE-ID、ゼロ時間予定、Microsoft終日予定を有限期間へ射影する。対応外形式は前回snapshotを維持して失敗させ、通信成功と形式対応を混同しない。
+47
View File
@@ -0,0 +1,47 @@
# 14. 予定・iCalendar・CalDAV・連絡先
状態:カレンダー部分は2026-09-22にローカル正本・Plan UI・限定CalDAVを実装開始。最新の契約・実装範囲・残作業は [カレンダー詳細設計](calendar-implementation.md) を参照。以下の旧順序/URI案より同設計を優先する。連絡先と外部同期は引き続き設計案。
## 四つのレイヤー
| レイヤー | 役割 | PagesWikiでの扱い案 |
| --- | --- | --- |
| Wiki URL | 人が開く説明・知識への入口 | rename可能なPage Path |
| iCalendar | 予定・タスク等の交換形式 | export/import、UIDと元データを保持 |
| CalDAV | カレンダー資源を扱うWebDAV拡張 | remote connector、将来の提供面 |
| CardDAV / vCard | 連絡先の通信 / データ形式 | 個人・共有address book |
iCalendarとCalDAVは同義ではなく、`.ics`を配信するだけでCalDAVサーバーにはなりません。vCardとCardDAVも区別します。[RFC 5545](https://www.rfc-editor.org/rfc/rfc5545)、[RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)、[RFC 6350](https://www.rfc-editor.org/rfc/rfc6350)、[RFC 6352](https://www.rfc-editor.org/rfc/rfc6352)。
## identity対応案
local item UUID、calendar UID、remote href、Wiki Page UUIDを対応表に持ちます。Wiki renameでUIDを変更しません。remote href変更は移動・再取得として確認し、同じ題名だけで統合しません。ローカル生成UIDはDomain名変更でも維持します。
予定はevent、タスクはtodo、連絡先はcontactの型付き状態です。説明用Pageは任意の参照であり、毎回ICS/vCardをHTMLへ変換して正本を置換しません。原形式のDocument snapshotを保持し、未対応propertyの欠落を検出します。
## 予定のモデル案
開始・終了、終日フラグ、timezone/TZID、繰り返しrule、例外、参加者、状態、source versionを分離します。終日をUTCの時刻に変換せず、時間帯なしの時刻も区別します。無限recurrenceは画面の対象期間内だけ展開し、件数上限を持ちます。
例外instanceのキーは元seriesとrecurrence identityです。単発の変更・series全体の変更をUIで分けます。参加依頼、回答、メール送信などのschedulingは単純な予定保存とは別の後続機能です。
## 同期と競合
connectorはremote ETagとlocal versionを別々に持ち、更新前の値で条件付き操作します。ETagをDocument SHA-256と仮定しません。対応サーバーではcollection sync-tokenを利用する案ですが、無効なtokenからの再同期と未対応時のboundedな全量照合も必要です。[WebDAV同期仕様](https://www.rfc-editor.org/rfc/rfc6578)。
通信失敗では外部削除と見なさず、tombstoneは確認できた削除だけです。両側で変更された場合はbase/local/remoteを比較し、内容を保存した競合状態へ移します。勝手な最新版上書きはしません。
## 連絡先
address bookの所有者・共有範囲、contact UUID、remote UID、複数メール/電話、名称、所属、写真の固定参照を持ちます。人物Principalとcontactは別です。メール一致だけでユーザーへ自動連結しません。重複候補を示し、mergeは変更前をexportできる確認操作にします。
## URL/API案と実装順
人向けは `/v/organizer`、APIは `/_/api/v1/extension/organizer.{calendar|contacts}/…` を候補とします。**未実装・未予約**です。DAV提供面はroot discovery、認証、標準メソッドとルーターの衝突を調査してから決めます。Wiki PathをそのままDAV collectionにしません。
1. ICS/vCard fixture、入出力preview、警告、重複防止。
2. local calendar/agenda・連絡先一覧、権限・version試験。
3. 選定サーバーに対するread-only connector。
4. 限定された双方向同期、最後に必要性が確認できたDAV提供。
CAL-1:終日・夏時間・例外。CAL-2:UID/href/Path変更。CAL-3:412競合・token失効。CARD-1:複数propertyと未知項目。DAV-1:権限失効・大量collection・app token失効。これらを完了条件にします。
+165
View File
@@ -0,0 +1,165 @@
# カレンダー拡張:正本・CalDAV・Plan UI
更新:2026-09-22。既存の「予定・iCalendar・CalDAV・連絡先」のうちカレンダー部分を具体化する。連絡先、タスク、メール、招待配送は別サブプロジェクト。
## 1. 判断と実装状態
正本を SQLite に置かない。カレンダー単位の manifest と月別 iCalendar ファイルを正本とし、DB は消して再構築できる検索索引に限定する。Wiki Page の HTML 化や revision に予定を埋め込まない。
初期実装は **限定された CalDAV メソッド実装**。完全な CalDAV サーバーの適合性を宣言しない。`DAV: 1` のみ返し、`calendar-access`、`calendar-schedule`、sync-token は未対応のまま広告しない。
| 項目 | 初期実装 |
| --- | --- |
| 正本 | カレンダーの manifest、月ごとの VCALENDAR/VEVENT |
| 検索 | SQLite に domain/calendar/UID・開始/終了・ETag を索引化 |
| 日時 | UTC DATE-TIME、終日 DATE、DTEND は排他的 |
| 保存 | 未知の VEVENT property を保持。UI編集は対象フィールドのみ更新 |
| 並行更新 | 強い ETag の条件付き更新、競合時412、無条件更新428 |
| UI | 年・月・週・日・起点31日一覧・水平タイムライン、詳細・作成・編集・削除 |
| 共有 | 所有者、ユーザー単位 read/write、明示的な匿名公開 |
| 無効化 | system extension `organizer.calendar` の既存スイッチ |
ローカルCRUDと正本の1予定表現では、RRULE/RDATE/EXDATE/RECURRENCE-ID、TZID/VTIMEZONE、floating時刻、DURATION、VALARM、VTODO、METHOD による scheduling を**入力拒否**する。外部購読に限り、検証済みのVTIMEZONE/TZIDと単一RRULEを有限期間のUTC/DATE予定へ射影する。受理後に検索から消えたり、繰り返しが単発予定に化けたりしないことを優先する。例外予定などの未対応が残るため、一般のカレンダーアプリを無制限に接続できる段階ではない。
## 2. URI
### UI
- `/v/plan`:最後に開いた表示種別の現在日。表示履歴がなければ現在週。
- `/v/plan/cal/yyyy`:年。
- `/v/plan/cal/yyyy/mm`:月。
- `/v/plan/cal/yyyy/mm/dd`:日。
- 同上の `/week`:月曜から日曜、その日を含む週。
- 同上の `/events`:その日から31日間の一覧。
- 同上の `/timeline`:その日の時間を左から右に配置。
- 同上の `/new`:その日を初期値に新規予定ダイアログ。
- `/v/plan/event/{UID}`:予定詳細。
- `/v/event/new`、`/v/event/{UID}/edit`:指定どおり作成・編集。
- `/v/calendar`:`/v/plan` への互換入口。
複数カレンダー選択は `?calendar=work,personal` のように `pretty_name` をコンマで連結する。各名は個別にURLエンコードし、区切りのコンマはそのままとする。表示設定ダイアログで複数選択・自分の既定値を保存できる。既定値はドメイン内のユーザー単位で、内部UUIDの配列をファイル `preferences/{principalUUID}.json` に保存する。無指定時は可視な既定値を使い、未設定・すべて失効した場合のみ可視な先頭カレンダーへフォールバックする。既定値による移動ではクエリを追加しない。匿名利用は個人設定を持たない。
`pretty_name` はドメイン内で一意(大文字小文字だけ違う名前も重複)。Unicode NFCの文字/数字、`-`、`_` が使用でき、空白・コンマ・スラッシュ・UUIDそのものは不可。最大120バイト。別途 `name` は自由な表示タイトルとして保持する。月別iCalendar正本の `NAME`([RFC 7986 §5.1](https://www.rfc-editor.org/rfc/rfc7986#section-5.1))、CalDAV collectionのdisplaynameにはpretty_nameを使う。VEVENT単体のUID/ETagやDAV資源hrefは名前変更の影響を受けない。名称の重複チェックはドメイン単位のlockで直列化する。
旧データのpretty_nameは `calendar-{UUID}` を安全な初期値とし、歯車から変更可能。旧UUIDクエリは互換受付してpretty_nameへ置換する。UUIDを保持する既定設定と予定所属はrenameに追従する。外部に配布した旧pretty_nameリンクのリダイレクトは未提供。
UIDはカレンダー内で一意。別カレンダー間に同じUIDがあり得るので、生成する詳細リンクはその予定のpretty_nameを1つだけ含める。複数表示の新規予定では、書込可能なカレンダーから作成先を選ぶ。Wiki Pathのrenameは予定UIDに影響しない。
### プロトコルと管理API
CalDAV入口:`/_/api/v1/caldav/`。既存のジョブ `/_/api/v1/event/` と混同しない。
2026-09-26更新:`organizer.calendar 0.2.0`で専用Basic認証・共通principal探索・初回全件同期・CLI resource名を追加。[予定・タスク共通CalDAV](caldav-common.md)が追加契約。以下の旧仕様に対しcollectionのDepth 1、上限付き全件REPORT、CLI指定filename、JSONイベント取得の`?resource=`が追加される。UTC/DATEに限定する書込プロファイルは維持する。
| URI | 操作 |
| --- | --- |
| DAV root | OPTIONS、PROPFIND Depth:0/1(可視カレンダー) |
| `/{calendarUUID}/` | PROPFIND Depth:0、REPORT calendar-query / calendar-multiget |
| `/{calendarUUID}/{base64url(UID)}.ics` | GET/HEAD、PUT、DELETE |
| `/_/api/v1/extension/organizer.calendar/calendars` | GET一覧、POST作成 |
| 同上 `/{calendarUUID}/settings` | PUT 設定/DELETEカレンダー、manifest version必須 |
| 同上 `/{calendarUUID}/events` | GET `?uid=`、POST作成/編集 |
| `/_/api/v1/extension/organizer.calendar/event?uid=` | 可視カレンダーからUID解決。複数一致は409 |
UIDは任意のテキストなのでDAVのファイル名へ直接使わずbase64urlにする。絶対URLのhrefや別カレンダーへのmultigetは受理しない。全件無制限のDepth:infinityやREPORTは提供しない。現在は作成を管理JSON APIで行い、MKCALENDAR/PROPPATCH/ACLは後続。
## 3. ファイルと障害復旧
```
documents/calendars/{domainUUID}/{calendarUUID}/
calendar.json
.lock
2026-09.{sha256}.ics
2026-10.{sha256}.ics
```
`calendar.json` は名前・所有者・公開設定・メンバー・version・月→ファイルSHA-256対応を持つ。月別ファイルは世代ごとに不変。VEVENTは開始月へ収納し、月をまたぐイベントは分割しない。
変更順序:カレンダーのプロセス間lock取得 → 現manifestとETagを確認 → 変更月の新ファイルを書きfsync → manifestをatomic renameしてディレクトリfsync → 未参照の旧世代を清掃。
9月から10月へ予定を移動する場合も、両月の新ファイルを準備してからmanifestを一度だけ置換する。中断した未参照ファイルは次の成功時に清掃する。過去世代を無限に保持する履歴設計にはしない。正本バックアップはmanifestとその参照先を一組で取得し、稼働中はlockと協調する必要がある。
DB表は `calendar_index_state`、`calendar_month_cache`、`calendar_event_cache`。manifest versionが変わったときだけ、hashが変わった月を索引へ反映する。DB反映前の中断は次回アクセスで修復する。DBだけが最新になりファイルが古い状態を正本とはしない。復旧時は3表を**一緒に**破棄し、正本から再構築する。
手動でICSを書き換える運用は未提供。hash名のファイルを直接編集しない。キャッシュ再構築時にはSHA-256を検証する。正本ファイルのACLは0600、ディレクトリは0700。HAの複数ノード同時書込やネットワークFSのロック保証は別途検証する。
## 4. 取得・キャッシュ・負荷
フロントエンドは対象期間の `calendar-query` でgetetagのみ取得。タブ内メモリのETagと一致する予定は再取得しない。変更分だけJSONの予定投影を取得し、同時取得は最大4件。独自にREPORTへ304を返す実装はしない。ICS GETではIf-None-Match/304を利用可能。
月をまたぐ予定は開始月のファイル列挙ではなく、DBの開始/終了の重なりで取得する。ゼロ時間の予定は開始時点が期間内なら一致。DATEとUTC日時を表示時に混同しない。UIの時刻入力・表示・日境界は**ドメイン設定のタイムゾーン**を用い、正本はUTCで保存する。DSTで存在しない時刻や二重になる時刻をドラッグ操作で暗黙補正せず、編集画面で再指定させる。DATEの検索境界差を補うためUIのREPORTは前後1日を加え、描画時に絞る。
週・日ビューは67〜400%の6段階で時間軸を拡縮する。100%以下は15分、200%は10分、300〜400%は5分単位で移動・リサイズする。予定中央のドラッグは長さを保った移動、上端は開始、下端は終了の変更である。同時刻帯で重なる予定は最大同時数分の等幅laneへ配置する。短い予定には操作可能な最低表示高を確保し、その表示領域同士も衝突しないlaneへ分ける。保存成功時はAPI応答の予定だけをタブ内集合へ反映してlaneを再計算し、期間REPORTや予定全件を再取得しない。時間列の空白をドラッグすると設定タイムゾーンの選択範囲を入力済みの新規予定ダイアログを開き、クリックだけでは作成しない。
上限:ドメイン256カレンダー、1資源256KiB、XML64KiB/深さ12、月5000件/16MiB、期間370日、結果5000件、multiget200件、lock待機5秒。超過は部分成功にせずエラー。ETagだけのREPORTは本文をparseしない。永続ブラウザキャッシュや共有CDNへの予定保存は行わない。権限を確認してから304・本文を返す。
## 5. 権限
カレンダー所有者が名前・公開設定・collaboratorを管理する。collaboratorは同じドメインの有効なユーザーで、`read` または `write`。writeには予定作成・変更・削除を含むが、共有設定の変更は含まない。readonlyアカウントの書込は不可。グループ共有・所有権移管・管理者による復旧は後続。
カレンダー全体の削除も所有者だけが行う。設定ダイアログで全予定を含む完全削除を確認し、`DELETE .../settings` に現在のmanifest versionを渡す。古いversionは412とし、削除対象の外部同期ジョブはqueuedなら取消、runningなら取消要求を付ける。正本ディレクトリを原子的に不可視化して削除し、SQLiteの3索引表を消す。ユーザー既定値に残ったUUIDは毎回の可視性検査で除外される。実行済みジョブ履歴とログは監査情報として削除しない。
匿名公開はカレンダー全体を対象とし、説明・場所を含めて公開する旨をUIで告知する。既存のドメイン公開上限がpublic、ドメイン有効、authorization_mode=enforcingのときだけ有効。上限を閉じれば次の取得から匿名アクセスを拒否する。公開範囲の狭い予定を混在させるには別カレンダーを使う。VEVENTのCLASSだけをアクセス制御として扱わない。
Page公開とは別の正本なのでCityのSpot/Pathへ暗黙に従属させない。将来Pageへの関連付けをしてもPage参照権限と予定権限は別途評価する。
## 6. RFC対応の検証と残タスク
基準:[RFC 5545](https://www.rfc-editor.org/rfc/rfc5545) / [RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)。パーサーは `github.com/emersion/go-ical` を固定バージョンで使用し、アプリ側でDTSTART必須、UTC/DATE、排他的DTEND、UID、不支持property、制御文字、必須項目を追加検証する。出力はCRLF・UTF-8を分断しない75octet折返し。ライブラリ採用だけをRFC適合の証明にはしない。
- [x] 単発UTC/終日、未知property保持、月境界、同時更新、キャッシュ再構築、公開取消の回帰テスト。
- [x] Plan各ビュー、期間REPORT、差分取得、設定・予定ダイアログ、所有者限定のカレンダー完全削除。
- [x] 外部購読用のTZID/VTIMEZONE(IANA、主要Windows名、定義内のSTANDARD/DAYLIGHT)と夏時間fixture。
- [ ] ローカル正本でのTZID/VTIMEZONE/floating対応、DURATIONの暦日演算。
- [x] bounded recurrence展開、EXDATE/RDATE、RECURRENCE-ID例外、時間範囲オーバーラップ、件数・本文量・対応頻度によるCPU/メモリ上限。
- [ ] 標準XML precondition/error、PROPFIND/PROPPATCH/MKCALENDARの適合性、principal discovery、`/.well-known/caldav`、Depthと未知filterの完全な検証。
- [ ] アプリ専用の失効可能なCalDAV credential、権限のread/writeスコープ、クライアント適合試験(現状は既存session Bearer)。
- [ ] collection sync-token、tombstone保持と期限切れの再同期。現状は期間REPORTが正しい集合を返す。
- [ ] バッチmultigetの単一索引snapshot化、大量calendarの一覧ページング、UI期間ごとのvirtualization。
- [ ] 専用ジョブとしてreindex/検証/容量統計、イベント資源監視、管理者向けバックアップ・restore・所有権復旧。
- [ ] グループcollaborator、イベントごとのvisibility、承認Inbox、共有変更監査、変更通知。
- [ ] 招待・参加回答・リマインダーはCRUDとは別のevent/scheduler連携。iTIPメール配送を無断で有効にしない。
- [x] 外部ICSの条件付きGET購読、外部CalDAVの期間REPORT/差分multigetによるread-only同期(下記制約あり)。
- [ ] 外部連携のdiscovery、OAuth、sync-token、取得期間の設定、競合UI付きの双方向同期。
完全なCalDAV適合性・繰り返し対応の完了までは「一般クライアント互換」の完了チェックを付けない。
## 7. 今回の検証記録
- `go test ./internal/calendar ./internal/server -run 'TestCalendar|TestPolicyForRequest'`:成功。
- Chromium:月・週・timeline・詳細の描画、設定タイムゾーン、400%/5分ズーム、中央移動、上下端リサイズ、重複予定の等幅配置、ダイアログによる作成/編集/削除、カレンダー名の変更、ETag一致時の本文再取得抑止を確認。
- 全体テストは `TestConfigBookmarksSaveAndPanelRegistry` が既存設定画面の `config-form-table` に横スクロールコンテナがないとして失敗。カレンダー画面には当該テーブルは追加していない。別UIタスクとして調査・是正する(テストを緩めない)。
## 8. 時間軸の操作
終日の入力・詳細表示では終了日を**含む**。同日開始・同日終了で1日の予定を作成できる。保存時だけ終了日にUTC暦日を1日加算し、編集・表示時には1日戻す。正本ICSとAPIのDTENDはRFC 5545の排他的境界を維持する。既存データの移行・外部予定の書換は不要。
トップバーはCity・直近の予定・通知・プロフィールの並び。直近の予定は既定カレンダー(未設定なら先頭1件)の今日から31日間を最大20件表示する。`GET /_/api/v1/extension/organizer.calendar/upcoming?date=yyyy-mm-dd` はログイン必須、毎回権限確認、no-store、5秒上限、カレンダー毎20件の本文取得上限を設ける。モーダルを開いたときだけ取得し、閉じたら中断する。通知と予定は背景スクロールを抑止した中央モーダルで、Escape/閉じるボタンに対応する。
日・週ビューは縦の時間軸、timelineは横の時間軸に予定を表示する。従来の週リストは `/v/plan/cal/yyyy/mm/dd/week/list` とし、先頭行に曜日を表示する。日・週の尺度は40/60/90/120 px/時から選択できる。
最後に開いた年・月・週・週リスト・日・timeline・予定一覧の表示種別だけをPrincipal単位でブラウザへ保存する。予定本文、カレンダー名、選択日、資格情報は永続化しない。予定の新規作成後は詳細画面へ遷移せず、作成を開始した表示種別と基準日へ戻して再取得する。新規作成専用URLから開始した場合も、保存済み表示種別(未保存なら週)へ戻る。
書込可能な予定の移動ハンドルをドラッグすると15分単位で日時を変更する。日・週では上下キー、timelineでは左右キーでも移動可能。期間の長さを保持し、Escapeでドラッグを取消す。存在しない/曖昧なローカル時刻への日・週移動を拒否する。保存は既存ETag付きAPIを通し、競合時には上書きしない。終日・外部読取専用の予定にハンドルは表示しない。ブラウザ試験で縦横の実マウス操作とキーボード操作を検証する。
## 9. 外部カレンダーの読み取り同期
新しい空のカレンダーを作り、所有者が「外部同期」ダイアログでICS URLまたはCalDAVコレクションURLを設定する。取得間隔は1分〜7日、手動同期・停止を提供する。外部同期を停止しても、取得済み予定と読み取り専用属性は保持する。双方向同期や、既存のローカル予定への混在取込は行わない。公開・collaborator設定は取込先の設定に従うため、私用フィードは非公開カレンダーで利用する。
- API:`PUT /_/api/v1/extension/organizer.calendar/calendars/{UUID}/source` で設定、同じURIへの `POST` で手動キュー投入。所有者限定、設定更新はmanifest version必須。
- 組込イベント `calendar.source.sweep` が60秒ごとに期限を確認し、`calendar.source.sync` を低優先度・カレンダー単位の重複抑制付きでキューへ投入する。実行状態・ログは既存イベント管理に統合。UIを開く必要はない。間隔は次回取得の目安でありキュー混雑により遅れる。
- ICS:ETag/Last-Modifiedを条件付きGETに利用する。304では予定を再書込しない。
- CalDAV:過去90日〜未来275日のREPORTでgetetagを取得し、変更分のみ100資源単位のcalendar-multigetで取得する。期間外はローカル投影に保持しない。コレクションURLを直接指定し、discoveryはまだ行わない。
- 完全な応答を検証してから全月snapshotとmanifestを更新する。取得失敗、未対応形式、部分的なmultiget、途中で変わったETagでは前回の予定を保持。正常な空集合は削除として反映する。安定したUID順で保存し、応答順の変化による書換を避ける。
- 上限:ICS本文8MiB、CalDAV各応答8MiB・予定本文合計8MiB、5000件の射影予定、ジョブ50秒。Outlookで約10秒かかる応答を許容するため、response header 25秒・HTTP全体45秒とする。2.6MiB超・4500件の合成fixtureを回帰試験に含める。
- Outlook公開ICSの `METHOD:PUBLISH`、`X-WR-CALNAME`、`VTIMEZONE/TZID`、単一 `RRULE`、Microsoft固有X-propertyを受理する。主要Windows TZIDはIANAへ対応付け、それ以外はSTANDARD/DAYLIGHTとTZOFFSETTOの遷移を同期期間について解決する。RRULEは過去90日〜未来275日の各予定へ安定UIDで展開し、内部正本はUTC/DATEのまま維持する。`X-MICROSOFT-CDO-ALLDAYEVENT:TRUE` のローカル午前0時境界はDATEの終日予定へ変換する。
- Outlookが出力する `DTSTART == DTEND` の時刻予定はゼロ時間予定として保持し、同じ境界のMicrosoft終日予定だけは排他的終了を翌日に正規化する。終了が開始より前、またはDATEとDATE-TIMEが混在する場合は予定内容をログへ出さず同期全体を失敗させる。
- 外部購読の解析済みプロパティ値・パラメータに混入したC0(タブを除く)、DEL、C1制御文字は正本化の前に除去し、予定へ `X-PAGESWIKI-SANITIZED:CONTROL-CHARACTER` 相当の印を残す。ローカルCRUDの厳格な入力検証は緩和しない。NUL、不正UTF-8、制御文字を含むUIDは同一性・構文破壊を避けるため購読全体を拒否する。
- RDATEとEXDATE(DATE/DATE-TIME、複数値)、RECURRENCE-IDによる移動・内容変更・取消を親RRULEへ合成する。例外の出力UIDは元のRECURRENCE-IDから安定生成し、移動後も同一インスタンスとして扱う。EXDATEと変更例外が同一回を指す場合は明示的な変更例外を優先する。
- 購読射影が親RRULEを省略し、`RECURRENCE-ID` 付きの変更回だけを含む場合は、取消回を無視し、DTSTARTを持つ回を元のRECURRENCE-ID由来の安定UIDで単発射影する。親がないためDTEND省略時の長さは推測せずゼロ時間予定とする。
- RDATEのPERIOD、RECURRENCE-IDの`RANGE=THISANDFUTURE`、DURATION、VALARM、floating時刻はまだ未対応。部分的に欠落させずフィード全体を同期エラーにし、前回snapshotを保持する。現段階でOutlookの全機能や一般プロバイダへの完全対応は宣言しない。
- 同期失敗はcompose logへdomain UUID、calendar UUID、protocol、処理段階、安全化した理由を出す。購読URL、認証情報、UID、タイトル、説明、場所、ICS本文はログへ出さない。
- HTTPS/443の公開アドレスのみ許可する。接続時DNS検証と接続IP固定、プライベート/loopback/link-local等の遮断、リダイレクト再検査、環境proxy無効によりSSRFを防ぐ。認証付きリダイレクトは同一origin限定。
- 任意のBasic認証資格情報は既存認証鍵を用いた暗号化とdomain/calendar束縛で保存し、APIに再表示しない。URLに購読トークンを含む場合は保護された0600のmanifestに保存される。URL/認証情報をジョブpayloadに入れず、取得エラーを秘匿化する。バックアップには正本に加えて認証暗号鍵も必要。
実プロバイダ接続試験、より広いiCalendar形式、資格情報更新・失効の監査、同期専用の容量/CPU指標、取得対象の管理者allowlistは後続タスクとする。
+33
View File
@@ -0,0 +1,33 @@
# カレンダーのスマートフォンUI
2026-09-25実装。iPhone SE相当の320×568/375×667と667×375横画面を対象。**Chromiumのタッチ・画面サイズエミュレーションで検証済み。Safari/iPhone実機の確認は未実施。** 同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。
## 操作と表示
- 小さい画面では、表示種別の7リンクをselectにまとめる。今日/前後/日付ピッカーは常時表示。
- カレンダー選択・更新・新規予定を残し、追加/設定/外部同期/表示対象は「⋯」メニューへ集約。権限による元の表示制御を引き継ぐ。
- 上部の重複ナビと重複見出しを省略。見出し自体はスクリーンリーダー用に維持する。
- 週ビューは細い7列にせず、縦画面で約1日、横画面で約2日の幅を確保。曜日/日付ボタンで同じ週の列へ横移動する。見出しの日付を押すと日ビューへ進む。PCの7列表示は維持する。
- 月ビューは日付と予定件数を表示し、詳細は日ビューで見る。狭いセルへの件名詰め込みは行わない。
- 一覧では日付/件名を優先。場所の列はスマホでは省略し、予定詳細で確認する。
## タッチ操作
coarse pointerでは通常、予定の上も空き領域もスクロールとpinch zoomを優先する。指が触れただけで時刻変更・範囲作成を開始しない。タップは予定の詳細へ進む。
時間グリッドの「編集操作」をONにした場合だけ、移動・開始/終了の伸縮・空き領域の範囲選択を有効化する。ON/OFFはaria-pressedで表現。PCのドラッグ・矢印キー操作は維持する。タイムラインの小さいドラッグハンドルはタッチでは隠し、予定詳細から時刻を編集する。
## Safariへの配慮
フォームの文字を16px以上、操作領域を40〜44pxに揃える。画面のzoomを禁止するviewport指定は追加しない。編集ダイアログはVisualViewportのheight/offsetを使い、ブラウザバーやソフトキーボードによる変化を考慮する。pinch zoom中はサイズ更新を停止する。CSSのdvh fallbackとsafe-area insetを併用する。
スマホのスクロール領域と編集ダイアログはbackdrop blurを外し、テーマの背景色でコントラストを確保する。予定データのキャッシュ/REPORT/ETag/タイムゾーン処理は変更しない。
## 検証と残TODO
- 合成ローカルカレンダーで320/375縦・667横、ページ横はみ出し、列幅、日付選択、スクロールと編集gesture切替、月の件数、設定メニュー、編集dialogの収まりを自動検証。
- 既存のPC CRUD・ドラッグ・resize・400% zoom・ETag試験を継続。
- 外部取り込みカレンダーの内容にはアクセスしない。
- TODO: Safari実機でソフトキーボード開閉、画面回転、pinch zoom、背景復帰、長い終日予定、多重重複予定を確認。端末・OSバージョンに応じた調整。
参考:[WebKitの動的viewport単位](https://webkit.org/blog/12669/new-webkit-features-in-safari-15-5/)、[MDN touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action)。
+39
View File
@@ -0,0 +1,39 @@
# 3. キャンパス・ドメイン・連携
状態:ローカル管理、外部キャンパス参加、署名付き設定配信は実装済み。コンテンツ同期・DRとは別機能。
## FQDNと配置
キャンパスの設定値はURLではなくFQDNです。ドメインのホスト指定が短い名前ならキャンパスFQDNのサブドメインとして扱い、FQDNならその値を使います。空のホスト名はキャンパスFQDN自身に対応し、未知Hostの受け皿にはしません。
表示用FQDNと配置先インスタンスは別の情報です。FQDNを指定しただけでは別インスタンスとは限りません。配置先は承認された候補から選び、同じFQDNの鍵フィンガープリント変更は同じ実体として黙認しません。
## 設定の所有者
- キャンパス管理:配下ドメイン、配置、参加トークン、キャンパスの共通情報。
- ドメイン管理:Wiki名、テーマ、記事・拡張設定、メンバー、権限。
- 外部キャンパス管理:コントローラから受け取った管理項目をローカルで独自に上書きしない。
- 秘密:実際に認証・接続するインスタンス側に保持し、一般設定manifestへ混ぜない。
ドメインの設定は個別です。同じキャンパスに属するだけで記事、グループ、認証セッションを共有しません。
## 参加と配信
コントローラ発行トークンで参加要求し、インスタンスidentityを承認します。設定manifestは署名と単調なsequenceを持ち、受信側は適用とcheckpoint更新を同一トランザクションで行います。古いsnapshotへの巻き戻しや同名の別authorityへの置換を拒否します。
入口設定を含むmanifest v2は、全承認済み配置先の対応能力を事前確認します。対応能力の申告は「適用完了」や「オンライン」の証明ではありません。反映ACKと鮮度の明示はTODOです。
`--add-external-campus` は通常経路、`--add-external-campus-http` は明示的な開発用HTTP経路です。HTTP許可を一般接続の既定値へ拡張しません。
## 継承の区別
キャンパス管理者のローカル継承には、付与元ごとの記録と失効処理があります。独立したローカル付与を消さず、継承を切ったときに派生権限だけを除きます。
Domain間PSKによるidentity・group継承は設計段階です。署名付き差分、失効、origin競合、鍵交代を含む同期契約と実装が必要です。キャンパスmanifestの配信やローカル管理者継承が完成したことをもって、任意ドメイン間の安全な権限同期が完成したとは扱いません。
## TODOと合格条件
- 反映ACK、設定管理の解除、削除ドメインの保持・GC。
- 同名・異originのグループ衝突、PSK失効、sequence欠落、鍵交換の試験。
- 秘密の外部管理と明示的なローテーション手順。
- 別インスタンス記事射影は、取得権限・失効・障害時の閉じ方を設計してから実装する。
+42
View File
@@ -0,0 +1,42 @@
# 21. 決定事項・矛盾の整理・未決事項
状態:既存設計の統合と、新規構想の判断台帳。設計案を実装完了に読み替えません。
## 原資料の読み替え
| 古い記述・混在 | 現在の読み方 |
| --- | --- |
| OIDCは形だけ、UserInfoだけを根拠にする | 署名・claim・state/nonce等のhardeningが入っている。詳細契約を優先 |
| CookieをやめてBearer一本にする | ブラウザCookieとAPI Bearerを目的分離して併用 |
| 匿名ナビゲーション・RSSは未実装 | 限定公開条件で実装済み。全metaや全依存物の公開ではない |
| 匿名公開はすべて毎Revision再承認 | 手動公開はそのまま。確認したStreet/Spotのみlive-head自動公開可能 |
| 個別記事の一覧登録だけが投稿方法 | 原子的な新規投稿APIと独立画面を追加済み |
| 同じCampusなら任意ノードでブログ射影 | 現行の参照型記事射影は同一インスタンスまで |
| resourceはブラウザを開いたときだけ記録 | 背景イベントで保存。表示更新と保存間隔は別 |
| groupプロフィールのnamespaceが設計のみ | 実装側にgroup画面・APIあり。機能ごとの完了度で読む |
| Asset名はinstance全体の名前 | mutable Asset名はDomain-local、Document hashは不変content identity |
| イベントキューがあるのでoutboxも完成 | queue、個別journal、transactional outbox配送は異なる |
| すべての文書はHTML正本 | 文章の正本HTMLと、バイナリ/固有形式の正本を区別 |
古い文書は削除せず、初期思想・変更理由・実装の追跡用に保持します。本書とコードが違う場合はまず差分を確認し、設計を理由に現在の安全制約を外しません。
## 新規ADRの案
| ID | 提案 | 状態・決めるための条件 |
| --- | --- | --- |
| ADR-O1 | organizerはtyped metadataと任意Page参照 | タスク初版は専用表+既存CAS Document Store(2026-09-24)。通常のObject閲覧・リンク・削除の権限境界を拡大せず、個人所有を確実に分離する。DBは捨てられる索引ではない。[実装契約](tasks-implementation.md) |
| ADR-O2 | task共通部+ticket workflow | 提案。番号・外部依頼者・遷移権限の要件確認 |
| ADR-O3 | ICS/vCard入出力→read-only DAV→双方向 | 推奨順。対象サーバー/clientを選んで互換表を作る |
| ADR-O4 | FreshRSS正本+PagesWiki connector+newsboat | 第一候補。利用環境・追加運用負荷を確認。内蔵readerは代案 |
| ADR-O5 | IMAP read-only、Wikiコピーは明示操作 | 初期設計方針。providerとsampleが実装前提 |
| ADR-O6 | HTMLパーツを先行し全面WYSIWYGは保留 | 提案。round-tripと操作改善の評価でgo/no-go |
| ADR-O7 | Wiki Pathと外部UID/hrefを分離 | 共通の設計制約。rename fixtureを全connectorで実施 |
| ADR-O8 | 外部stateの変更は別段階の明示権限 | 共通の設計制約。既読・削除・送信の監査と確認 |
## 未決事項
利用するFreshRSSの有無と版、対象CalDAV/CardDAV client、IMAP provider、taskの共有単位、ticketの依頼者公開範囲、保持期限、外部接続を許可するhost、RPO/RTO、WYSIWYG採用基準です。これらが未決でもlocal fixtureと設計は進められますが、外部サービスを勝手に立ち上げたり資格情報を流用したりしません。
## 文書運用
新しい決定には理由・代案・互換影響・試験を残します。変更履歴ledgerと現状の説明を分けます。日本語統合版から詳細原資料へ辿れる対応表を維持し、英語版は同じchapter IDで追従させます。
+61
View File
@@ -0,0 +1,61 @@
# 11. システム拡張・通知・協働
状態:信頼済みビルトインcatalogと設定入口あり。任意第三者コードのロードは未実装。
## アダプタとシステム拡張
アダプタは特定Documentを開く・編集する役割、システム拡張は活動、通知、コメント、予定、メール、RSS、検索provider等のサービスです。外部サービス連携用URLに汎用管理権限を押し込めません。
現行catalogは `/_/api/v1/extension/`、個別操作は `/_/api/v1/extension/{id}/…` の系統です。catalogに載っても任意コード実行や権限付与は許可されません。
## 共通manifest案
安定ID、版、互換範囲、scope、設定schema、必要capability、outbound host、secret reference、購読event、checkpoint、実行image digest、署名、CPU/メモリ/時間/出力制限を宣言します。
設定はinstance / Domain / Principalを区別します。ホスト所有のフォームを基本にし、独自UIはsandboxと型付きメッセージに限定します。無効化はデータ消去と別操作です。export、移行、rollback、孤立データの保持期間を必須契約にします。
## 協働機能の正本
| 機能 | 保存するidentityと状態 | 漏えいさせないもの |
| --- | --- | --- |
| 最近編集 | event、actor、Page/Revision、Domain sequence | 現在読めないPageのタイトル |
| 最近閲覧 | 本人の閲覧履歴と保持期限 | 他者の私的な閲覧履歴 |
| いいね・ランキング | Page、反応者、期間集計、計算版 | 非公開Pageの順位や件数 |
| 品質評価 | rubric版、評価者、対象Revision、根拠 | 機械評価を人の決裁と偽る表示 |
| inline comment | Revision、範囲、周辺hash、孤立状態 | 改訂後の別文章への誤結合 |
| コメントthread | Page、投稿・編集履歴、moderation | 削除・権限失効後の本文 |
| 通知Inbox | event、受信者、配送・既読 | 保存時点の権限で固定した本文 |
通知を開く時点で権限を再評価します。権限を失った相手へ昔のタイトル付きメールを新規送信しません。送信済み外部通知の撤回不能性は別途表示します。
## 外部検索・埋め込み・テーマ
ローカル検索にない場合も、検索語を自動でGoogle等へ転送しません。宛先と送信語を示して選択させます。GROWI、PukiWiki、他PagesWikiは個別API契約・資格情報・上限を確認します。
Spotify/YouTube等のwidgetはprovider許可と同意プレースホルダを使います。文書内の任意scriptを実行しません。時間・日没によるテーマは型付き条件とCSS theme IDを扱い、位置情報を無断取得しません。
## ネットワーク・資産管理拡張(設計TODO)
IPアドレス管理(IPAM)、DNSゾーン/レコード管理、機器・ソフトウェア等の資産管理は、通常のWiki本文を直接書き換えるアダプタではなく、監査可能なシステム拡張として設計します。正本はそれぞれ `network_prefix`、`dns_zone`/`dns_record`、`asset_item` の型付きエンティティとし、説明・手順・添付資料だけをPage/Assetへの参照で持ちます。
| 拡張 | 最初の範囲 | 外部副作用と権限 |
| --- | --- | --- |
| IPAM | prefix、address、予約・割当、重複検査、CIDR表示 | read/writeを分離し、割当変更は承認と監査を必須化 |
| DNS | zone、record、TTL、所有者、検証済みtarget、差分 | zone単位の管理者、DNS providerへのapplyはdry-run→承認→idempotent apply |
| 資産 | asset、serial、owner、場所、状態、保証・関連Page | 個人情報・秘密値を本文や検索snippetへ出さず、履歴と廃棄を保持 |
外部DNSやCMDBへ接続する場合も、secret reference、許可origin、rate limit、最終同期時刻、providerのrevision/etagを保存します。DNSの名前解決やIPスキャンをページ表示中に実行せず、イベントキューのbounded jobにします。削除・再利用・移管はsoft deleteと競合検知を経てから行い、失敗時は外部状態と内部状態の差分を通知Inboxへ送ります。API候補は `/_/api/v1/extension/network.ipam/*`、`network.dns/*`、`inventory.assets/*` とし、schemaが固まるまで実装しません。
## CSV/表・スライド拡張(設計TODO)
CSVをPage本文へ複製せず、認可済みの別Documentをテーブルとして投影するmacroを用意します。候補構文は `{{csv:/data/items.csv range=A1:H200 header=true}}` とし、Path、Revision(またはasset hash)、列・行上限、表示モードを正規化してキャッシュキーに含めます。macroは表示時にboundedなProjectionを作るだけで、結果HTMLを正本へ逆流させません。CSV Editorは元Revisionを編集し、表投影とは別の操作・競合・権限として扱います。
交換形式はRFC 4180互換CSV(UTF-8、CRLF、引用符・改行を含むfield、BOMの扱いを明示)を第一正本とします。複数シート、型、数式、結合セル、書式が必要な場合はODSを別アダプタ/Assetとして扱い、CSVへの不可逆変換を黙って行いません。行数、列数、セル長、総バイト、ネストmacroを制限し、malformed inputは安全なテキスト表示へfallbackします。
スライドは、Markdown/HTMLの正本からReveal.js互換のProjectionを生成する連携アダプタを設けます。HedgeDoc、Slidevは外部originのホスト型アダプタとして、保存・公開・ユーザー情報をPages Wikiの権限へ自動昇格させず、read-only preview→明示的なimport/saveの順にします。JSを使用できない環境向けには、CSS scroll-snap/`:target`/print CSSだけでページ送りできるCSS-only Slide Editorを別実装します。外部ランタイム停止時は静的HTML/Markdownへ安全にfallbackし、任意script、remote import、iframe権限を本文から許可しません。
ネットワーク図ではnwdiagを追加候補とします。ソースをbounded parserで検証し、renderer version/theme/document hashをキーに静的SVGをキュー生成します。include、外部画像・font、未知directive、危険なSVG属性は拒否し、renderer停止時はescaped sourceまたは最後に検証済みの静的画像へfallbackします。編集アダプタの保存はone-use ticketと楽観的Revision競合を使い、Kroki経由の場合もorigin、timeout、quotaを明示します。
## 最初に作る共通部
outbox、actor provenance、現在権限で絞るprojection、設定のsecret参照、connectorの予算と再試行、export/削除です。機能別に通知・認可・秘密管理を作り直さないことを次章以降の前提にします。
+41
View File
@@ -0,0 +1,41 @@
# 15. RSSビューア・FreshRSS・newsboat
状態:設計案。既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。
## 選択肢と推奨する試作順
| 案 | 正本 | 利点 | 追加する責任 |
| --- | --- | --- | --- |
| PagesWiki内蔵reader | ローカルの購読と状態 | Wiki保存と一体のUI | 取得・既読・同期・client対応を全て持つ |
| FreshRSS connector | FreshRSSの購読・既読 | 既存reader資産を利用 | API互換性、権限、cacheと失効 |
| newsboat単独の橋渡し | newsboat側の購読・状態 | CLI利用に合わせやすい | ローカル連携経路・export/importの設計 |
FreshRSSにはGoogle Reader互換APIがあり、APIの有効化と専用passwordを使います。newsboatにはFreshRSS連携が用意され、カテゴリのtag化やstar操作を扱えます。[FreshRSS公式API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)、[newsboat公式マニュアル](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)。
このため最初の候補は **FreshRSSを正本、PagesWikiを読取connector、newsboatを同じFreshRSSのclient** とする構成です。これは設計上の提案で、ユーザー環境のFreshRSS導入・採用決定ではありません。PagesWikiがnewsboatをサーバー上で起動したり、そのSQLiteを共有したりする必要はありません。
## 読取MVP
購読一覧、フォルダ、記事一覧、外部原文、Wiki保存を提供します。初期段階では表示しただけでFreshRSSへ既読を送りません。UIには「読取専用・既読は同期していない」と明示します。ブラウザへFreshRSS password/tokenを渡さず、backend connectorがsecret参照を使います。
最小cache案はsource UUID、remote feed/item ID、title、safe excerpt/body hash、canonical URL、published/updated/fetched時刻、remote state/versionです。IDなしRSSにはfeed単位の保守的な代替キーを使い、題名だけで重複排除しません。Atomはentry IDと更新情報を持つ形式です。[Atom仕様](https://www.rfc-editor.org/rfc/rfc4287)。
## 既読・star同期を追加する条件
server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。
FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。
## 内蔵fetcherを選ぶ場合
定期event、条件付きGET、host別同時数、timeout、応答サイズ、展開サイズ、backoffを設けます。XML外部entityを無効にし、feed HTMLを安全化します。redirect/DNSを含むSSRF対策、外部画像の同意、個人購読URLや認証情報の秘匿が必要です。
OPMLは購読の入出力として扱い、既読・star・全本文のバックアップと同一視しません。importはpreview・追加/置換選択・重複確認を行い、既存購読を黙って削除しません。
## Wiki保存と権利・公開
既定はURL、出典、短いメモの保存です。全文保存は取得可能性・利用条件・個人用途等を確認する独立操作とし、feedが短いからといって有料記事を自動取得しません。保存先が自動公開範囲なら内容と添付の公開を明示確認します。
## TODOと受け入れ
RSS-1:read-only FreshRSS fixture。RSS-2:安全な一覧と出典付きWiki保存。RSS-3:必要なら既読/star送信。RSS-4:内蔵reader採用判断とOPML。オフライン、欠落ID、巨大feed、未知HTML、同期再送、他user情報、feed削除後の保存Page維持を試験します。
+38
View File
@@ -0,0 +1,38 @@
# 17. HTMLパーツとWYSIWYGの判断
状態:設計案。全面WYSIWYG採用は未決定。既存エディタを置換しない段階的改善を第一案とします。
## 解決したい問題
表、画像とcaption、引用、注意書き、コード、リンク、macro、埋め込みを毎回手書きする負荷を減らします。単にHTMLを隠すことより、既存文書を壊さず効率よく編集できることを重視します。
## 段階案
1. Source+Projection previewを保ち、HTMLパーツ挿入paletteを加える。
2. 選択範囲の整形、リンク・表・画像の型付きdialogを追加する。
3. 対応するblockだけを視覚編集し、未知blockはread-only islandまたはsource編集へ戻す。
4. 完全WYSIWYGはfixture評価と操作上の効果が確認できた場合だけ採用判断する。
HTMLパーツは安定ID、版、schema、HTML template、preview、許可属性、必要providerを持ちます。挿入時に文書へ具体化するパーツと、動的macroを区別します。パーツ更新で過去Revisionを勝手に書き換えません。
## 保存契約
canonical HTMLと編集モデルと安全な表示HTMLは別です。preview展開済みchildren、閲覧者ごとのリンク、署名URL、session値を保存しません。unknownな属性を無言で削除するeditorは、その文書を視覚編集できると表示してはいけません。
保存は対象Page、編集開始Revision、言語、期待versionを照合し、競合時に選択・差分確認へ戻します。autosaveは下書きと本Revisionのどちらかを明示し、previewしただけで公開headを進めません。自動公開範囲では保存が公開へ直結することを表示します。
## round-trip fixture
- children等のmacro、asset provenanceと固定hash、embedded-object。
- code/pre、入れ子list、table、caption、非ASCII Path、RTL、複数言語。
- 未対応HTML、コメント、アクセシビリティ属性、長文・巨大table。
- paste時のscript/event属性/外部参照、安全化後と正本の違い。
- undo/redo、IME変換中、選択維持、キーボード、screen reader。
比較はbyte一致だけでなく、許可した正規化以外の意味・依存参照・未知blockを失わないことを検査します。変更なしで保存した場合に大量diffを作るeditorも不合格候補です。
## 採用判断の条件
HTMLパーツだけで主な不便が解決するならそこで止めます。完全WYSIWYGは、round-trip・IME・大規模文書・保守性・ライセンス・bundle負荷を比較したADRを作ってから選びます。特定ライブラリ採用や共同編集CRDTの導入は今回決めません。
EDITOR-1:fixtureとpalette schema。EDITOR-2:少数パーツの挿入。EDITOR-3:限定block prototype。EDITOR-4:比較評価とgo/no-go。共有編集は別の権限・競合・接続設計を必要とする後続事項です。
+31
View File
@@ -0,0 +1,31 @@
# 19. 多言語と設計書の配信
状態:Revision言語とfallback、日英UIの基盤あり。全画面の言語選択・翻訳管理・公開版の対応は継続課題。
## 同じ知識、同じPath
Pageは言語中立で、RevisionにBCP 47言語tagを持たせます。同じ章の日本語と英語を別Pageとして増やすのではなく、同じPage UUIDの `ja` と `en` を将来の配信先とします。
UI locale、本文の言語、Campus/Domainの既定言語は同じ設定ではありません。本文が日本語でも英語UIを使えます。`und` は言語未指定・legacy互換であり、「全言語で同じ内容」という保証ではありません。
## 解決と権限
明示指定、Accept-Language、地域tagの基底、Campus/system既定、und等を考慮する既存基盤があります。明示選択のURLや全endpointでの一貫性は別の完成条件です。fallbackで別言語を返す場合には選択された言語を把握できるUIが必要です。
非公開の日本語Revisionを英語fallbackで漏らしたり、その逆を起こしてはいけません。公開承認は言語headと正確なRevisionの関係を含めて検査します。自動公開ルールでは各言語の現在headも対象になる点を管理者へ示します。
## 今回の設計書配置
リポジトリの `docs/design/ja/` に日本語の編集元を置き、章IDをファイル名で安定化します。Wikiは `/lab/pageswiki-dev` を総目次とし、その配下へ同じ章IDで配置します。章番号は題名の表示順であってURL identityにしません。
配信用にMarkdownをHTMLへ変換し、`ja` Revisionとして保存します。日本語版を理由に既存英語資料を削除しません。Wiki側の公開権限を追加・変更しません。
英語化は原資料を単に一括アップロードするのではなく、日本語版の章ID・現在状態・決定事項と対応させます。原資料には古い構想が残るため、そのまま最新英語版とは扱えません。
## 翻訳台帳の案
`chapter_id, source_lang, source_hash, target_lang, translated_from_hash, reviewed_at, status` を持ち、元章の変更でstaleを検出します。翻訳の自動生成とreview済み公開を分けます。言語を切り替えると別の章に移動しないことを検証します。
## TODO
言語選択UI、lang別history/diff、translation stale表示、明示指定とcanonical、Content-Language/Vary/cacheの整合、公開言語別の失効、英語版のreview。これらが整うまでは英語の中間資料はリポジトリで保持します。
+53
View File
@@ -0,0 +1,53 @@
# PagesWiki 開発設計書
更新日:2026-09-19。日本語の統合設計版。実装の変更履歴ではなく、現在の境界と次の設計判断を確認するための入口です。
## この設計書の読み方
- **実装済み**:利用できる機能の範囲。関連する制約や未監査部分も併記します。
- **設計案**:今回具体化した方針。API・テーブル・既定値は、実装や互換性試験で確定させます。
- **TODO**:未実装の作業。記述やURL例が存在しても利用可能とは限りません。
- **保留**:安全性・運用方式・外部環境の選択が必要で、現時点では着手しません。
既存の英語・日本語の原資料はリポジトリに残します。初期構想と追記が混在するため、現状の読み取りでは本書の状態表示と、対応実装・テストを優先します。チェック済み項目も製品全体の完成を意味しません。
## 第I部 基盤
1. [設計思想と責務の分離](/lab/pageswiki-dev/principles)
2. [アドレス・保存・アセット](/lab/pageswiki-dev/address-storage)
3. [キャンパス・ドメイン・連携](/lab/pageswiki-dev/campus-federation)
4. [Knowledge City と案内図](/lab/pageswiki-dev/knowledge-city)
5. [認証・グループ・権限](/lab/pageswiki-dev/auth-permissions)
6. [公開・承認・共有・匿名ナビゲーション](/lab/pageswiki-dev/publication)
## 第II部 利用機能と実行基盤
7. [ビューア・エディタ・連携アダプタ](/lab/pageswiki-dev/viewer-editor)
8. [検索・ツリー・ホーム・設定画面](/lab/pageswiki-dev/navigation-search)
9. [イベント・キュー・リソース監視](/lab/pageswiki-dev/scheduler-resources)
10. [ブログ・日記・公開ドメイン射影](/lab/pageswiki-dev/blog-diary)
11. [システム拡張・通知・協働](/lab/pageswiki-dev/extensions)
## 第III部 オーガナイザーと編集拡張の設計案
12. [オーガナイザーの共通モデル](/lab/pageswiki-dev/organizer)
13. [タスクとチケット](/lab/pageswiki-dev/tasks-tickets)
- [個人タスク・プロジェクトの実装契約と次段階](tasks-implementation.md)(2026-09-24)
- [個人タスクのCalDAV/CLI連携](task-caldav.md)(2026-09-26、本番反映済み)
- [時間枠とPomodoroの実装契約](task-planning-focus.md)(2026-09-25)
14. [予定・iCalendar・CalDAV・連絡先](/lab/pageswiki-dev/calendar-contacts)
15. [RSSビューア・FreshRSS・newsboat](/lab/pageswiki-dev/feeds)
16. [IMAP取り込みとメールからWikiへの保存](/lab/pageswiki-dev/mail)
17. [HTMLパーツとWYSIWYGの判断](/lab/pageswiki-dev/html-editor)
## 第IV部 運用・実装計画
18. [性能・保全・外部ストレージ・HA/DR](/lab/pageswiki-dev/operations)
19. [多言語と設計書の配信](/lab/pageswiki-dev/i18n)
20. [実装順序と受け入れ条件](/lab/pageswiki-dev/roadmap)
21. [決定事項・矛盾の整理・未決事項](/lab/pageswiki-dev/decisions)
22. [原資料との対応と外部仕様](/lab/pageswiki-dev/sources)
## 今回の範囲
今回行うのは設計の再整理と日本語設計書の配置です。オーガナイザー、外部サービス、DAVサーバー、メールアカウント、公開権限の新設は行いません。設計書の配置も匿名公開の許可とは別です。
+38
View File
@@ -0,0 +1,38 @@
# 4. Knowledge City と案内図
状態:階層、境界、案内図、URL推論・編集の初期実装あり。自動整理の完全な整合性と大規模化は継続課題。
## 街の役割
Domainを一つのKnowledge City、Quartierを学区・街区、Streetを通り、Spotを知識の拠点として扱います。道路交通図ではなく、西洋建築の街区・中庭・入口を手がかりに知識へ到達する案内図です。
Spotを開くと、その拠点と周囲のPageを探索できます。ポータルPageは説明の入口であって、配下の一覧を失わせる自動転送の代用品にはしません。
## Path境界と多重参照
`/life`、`/life/home`、`/life/home/kitchen` をQuartier、Street、Spotへ対応させる例では、子境界は親の厳密な子孫です。同階層境界の重複はprimaryな所属の曖昧さを避けるため制限します。移動・統合では境界と親子関係を一緒に検証します。
Pageのprimary所属はPathから推論し、明示的なSpot参照は別のグラフ辺として持ちます。他のSpotへ紹介してもPageを複製せず、所属させただけで閲覧権限を与えません。Spotの下へ別のSpotを任意にネストさせる操作は現行モデルの階層ではありません。
## 案内図の表示規約
- Domainで生成した街の幾何をQuartier・Streetへ割り当て、ズームで文脈を保つ。
- Page数は相対重みだけでなく、少量のStreetを小さくする規模の目安にも使う。
- 未整理Pageは黄緑の個別ポイント。意味のない重複Spot名を増やさない。
- ラベルは原則水平。未ホバー時は場所を把握でき、ホバー時は対象を強調する。
- Spot近接・ラベル重なり・クリックとドラッグの判定を試験する。
- メニューはモーダルへ集約し、地図ポップアップは地図中心。ESC、矢印、WASD/HJKLを既存操作と衝突させない。
- 戻る・進むはアプリ内の状態遷移として扱い、URLの恒久履歴と同じものだと説明しない。
## URLからの自動整理
設計案は「推論結果を無条件に再生成」ではなく、手動編集を保護するreconciliationです。生成元、生成版、手動上書き、除外tombstoneを記録し、同じ入力なら変更なしに収束させます。
更新トランザクションと共通outboxを接続し、作成・編集・rename・削除を記録します。
DomainごとのCity consumerは10秒周期でイベントをdebounceし、URLからの自動計画を
背景キューで実行します。成功時だけwatermarkを進め、失敗時は再試行します。完全な
所有権・分散consumer・通知配送はTODOです。
## 性能・認可のTODO
現在のWorker生成や表示数上限だけでは、サーバー側で全体を読む問題は解決しません。局所的な階層取得、Pageのcursor、directory索引を先に整備します。権限で除外した名前・件数・ポータル・辺をcacheから復活させないことを合格条件にします。
+33
View File
@@ -0,0 +1,33 @@
# 16. IMAP取り込みとメールからWikiへの保存
状態:設計案。初期はメール原本を変更しない読取専用取り込み。SMTP送信は別機能。
## データと識別
account、mailbox、UIDVALIDITY、UIDを組み合わせてremote identityを持ちます。Message-IDは重複・欠落があるため補助情報に留めます。UIDVALIDITY変更は新しい世代として再照合し、UIDだけで別のメールを上書きしません。[IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)。
原MIME/EMLは不変Documentとして保存し、headers、本文part、添付、thread候補を派生metadataへ分けます。メールは私的collectionに属し、必要なものだけWiki Pageへコピーします。メールアドレスとローカルPrincipalを自動同一視しません。
## 初回取り込みと増分
フォルダ・期間・件数・サイズを選んでpreviewします。UID範囲を小batchで取得し、Documentとmetadata確定後にcheckpointを進めます。既読を付けない取得方式を使い、初期実装ではSTORE、MOVE、EXPUNGE等の変更操作を行いません。本文取得には非既読化の `BODY.PEEK` 等の意味を検証します。[IMAP仕様](https://www.rfc-editor.org/rfc/rfc9051)。
切断・timeoutは再試行し、外部の削除とは扱いません。IMAP4rev1互換、OAuth、サーバー固有のlabel/folder挙動は対象providerを選んだ上でfixtureにします。IDLEを採用しても定期照合を残し、全accountで無制限な接続を保持しません。
## 表示
既存EML parser/viewerを再利用し、HTMLはinert処理または分離表示にします。remote画像は既定で読み込まない案です。CID参照はそのメールの添付へ限定し、別のprivate Documentを指せません。添付名のPath traversal、巨大multipart、圧縮bombを制限します。
## Wikiへコピーする操作
確認画面で、宛先Path、題名、本文形式、添付の選択、出典リンク、公開見込みを表示します。共有メールでも自動公開はしません。`copy_receipt(account,message,destination,request_id)` 等で再送を識別し、Page・Revision・固定添付参照・監査を原子的に確定する案です。
コピーした後、元メールが消えてもWiki Pageを消しません。逆にmirrorの保持期限削除で、Wikiから参照されるDocumentをGCしません。コピーは既読・移動・削除・返信を同時に実行する操作ではありません。
privateメールをautomatic公開範囲へ入れると公開されるため、宛先policy versionを確認時と書込時で照合します。公開範囲が変化したら409等で再確認させます。本文を読めることと、外部へ公開できることを混同しません。
## 運用とTODO
MAIL-1:read-only小規模fixtureとcheckpoint。MAIL-2:EML表示・添付境界。MAIL-3:copy-to-Wikiとpolicy競合。MAIL-4:保持・export・account解除。双方向既読同期やメール送信は後続の明示選択です。
認証失敗のbackoff、accountごとの予算、暗号化secret、ログのheader/body秘匿、再取得上限を設けます。UIは最終成功と遅延・失敗を表示し、未取得を「メール0件」としません。
+31
View File
@@ -0,0 +1,31 @@
# 8. 検索・ツリー・ホーム・設定画面
状態:検索・children・Tree・ホーム・ブックマーク・設定整理の初期機能は実装済み。大規模索引と共通サイドバーは継続課題。
## 閲覧の入口
トップバーの検索はhome PathではなくDomain全体の `/` を基準にします。指定フォルダ内の検索とはモードを分けます。結果は全文だけでなくタイトル・Path・City要素のどこに一致したかを示し、Quartier/Street/Spotを上位にまとめます。
ファイル種別、拡張子、作成・更新日を候補取得の前に適用します。snippet生成失敗で結果全体を消さず、HTMLをそのまま検索結果へ注入しません。日本語の部分一致・現在Revisionだけの索引は残課題です。
## childrenとTree
childrenは現在Pathを既定にし、表示形式は本文macroの `view` 引数ではなくナビゲーションのアイコン操作で切り替えます。仮想フォルダでは設定により配下を表示します。サムネイルは描画を妨げず非同期取得します。
`/v/tree/{path}` は範囲を限定します。展開・全展開・全折りたたみ状態の保持、複数選択、rename・移動・削除はPath操作と一致させます。一般の子一覧から予約ユーザー領域を混入させません。再帰操作は事前の全対象確認と競合検出が必要です。
## ホームとブックマーク
通常トップバー型、中央検索型、検索+セクションカード型を選びます。セクションは手動URL/Path、または指定親の子リンクを表示します。設定は歯車のポップアップで、閲覧画面を編集フォームで埋めません。カード列はviewportに適応します。
外部ブックマーク連携は、手動登録と同期由来を区別し、同期時にローカル項目を削除しません。
## 設定画面
基本・認証・ドキュメント・拡張・運用等のグループとサブパネルを使います。選択したパネルだけ非同期で読み込みます。フォームの入力をpollingで上書きしません。トグルの装飾には実際のlabel・フォーカス・キーボード操作を残します。
テーブルは一行中心、詳細は展開またはポップアップへ。非JSONの403等をJSON parse errorに置き換えず、元の原因を表示します。
## TODO
directory索引と不透明cursor、権限付き検索の十分なrecall、共通サイドバー、個人ブックマーク、関連するテーブルのアクセシビリティ試験。キャッシュは認可結果の長期保存にせず、現在の権限を再評価します。
+42
View File
@@ -0,0 +1,42 @@
# 18. 性能・保全・外部ストレージ・HA/DR
状態:単一writerのSQLite運用、限定付きジョブ・cache、バックアップ手段あり。HAと外部保存は別途設計・検証が必要。
## 現状と性能優先順位
複数インスタンスがあっても、同じDBを共有するHAではありません。各SQLiteとDocument Storeのauthorityを区別します。コンテンツを読む要求に、全履歴走査、全文body hydration、巨大archive展開、外部接続待ちを持ち込まないことが最優先です。
| 課題 | 次の修正方向 | 完了を判定する試験 |
| --- | --- | --- |
| 全Path集計 | directory索引・局所query・cursor | 大階層で候補数とDB時間が限定される |
| 全City取得 | shallow projection・遅延Page取得 | 小範囲表示で全体を読まない |
| 歴史RevisionのFTS | current-only、安全なplain text索引 | 更新・削除・日本語検索・権限失効 |
| 大容量restore | immutable参照再利用・stream | heapがpayloadサイズに比例しない |
| decoder | process隔離・重み付き予算 | timeout/cancel/メモリ上限で確実に終了 |
| 失効とcache | generation+要求時認可 | 古い一覧からprivate内容を復活させない |
上限を増やす前にquery planと現実的なデータ量を測ります。公開ページの匿名cacheと認証ユーザーの認可cacheを同一にしません。
## 保全
DBだけでなくDocument Store、設定、復旧に必要な鍵を区別してバックアップします。稼働SQLiteを単純copyせず、online backup等の整合した手段を使います。Documentの固定hash検証、参照整合性、戻し手順をfixtureまたは別環境で確認します。
削除・復元は現行権限、全Path binding、依存参照、保持期限を確認します。バックアップ復元による過去権限復活には運用上の失効再適用が必要です。秘密を一般のWiki設計書やログへ複製しません。
## 外部ストレージ案
Document backendはStat/Open/ReadAt/PutIfAbsent/Verify/DeleteUnreferencedを持ち、SHA-256 identityを維持します。S3 key・ETag・URLをDocument identityとみなしません。multipart、短命URL、Range、GC、read-after-write確認を試験します。
WebDAV/SSHFSの可変ファイルとimmutable CASは別です。最初はread-only connector/import、マウントは専用sidecar等の運用責務としWeb要求でmountしません。SSH host key、outbound制限、secret管理が前提です。
## ファイル監査
MWDB/Karton等の接続はpending/clean/suspicious/malicious/error/expiredの状態と、engine・版・hash・時刻・由来を持つ非同期処理を案とします。監査必須の範囲ではcleanがない間のviewer/download/adapterを閉じます。scannerへ機密本文を送る操作には別の送信方針が必要です。
## DRとHAの順序
コントローラDRは署名manifest journal、鍵の保全、sequence、昇格epoch、旧leaderのfencingから設計します。記事DBとDocumentの複製は別の責務です。Campus manifestは記事バックアップではありません。
LB/HAにはsession失効共有、job lease、cache invalidation、uploadのnode非依存、WebSocket drain、proxy origin検証を要します。SQLiteをネットワーク共有して複数writerで動かす構成は採りません。fenced single-writer+replicaか、適切なmetadata backendを先に選びます。
RPO/RTOは目標値をユーザーと決め、復旧訓練の実測で保証範囲を定めます。現在の構成に無根拠な無停止・無損失を約束しません。
+45
View File
@@ -0,0 +1,45 @@
# 12. オーガナイザーの共通モデル
状態:設計案。今回は設計のみで、外部アカウント登録や同期を有効にしません。
## 目的と最初の範囲
Wikiの知識と、予定・タスク・連絡先・受信情報を相互に参照できる入口を作ります。メール、RSS、カレンダーの既存サービスを全て置き換えることは初期目標ではありません。
初期の画面は「今日」「タスク」「予定」「受信情報」「連絡先」を切り替える、薄い集約画面とします。各コレクションの権限で絞り、未読件数すら他者へ漏らさない設計です。共有の通知Inboxと、メール受信箱・RSS未読一覧は別物です。
## identityの案
| 概念 | 安定したキー | 別途持つ可変情報 |
| --- | --- | --- |
| collection | ローカルUUID、Domain、所有Principal/共有scope | 表示名・接続先 |
| item | ローカルUUID、kind、collection | status、title、version |
| Page参照 | Page UUID、参照Domain | 現在のPath・表示URL |
| remote binding | connector UUID、remote collection、remote ID | remote href、ETag、checkpoint |
| connector | ローカルUUID、provider、owner、許可scope | secret_ref、health、最終成功 |
イベント、タスク、メール等を無型の一つのJSON表へ押し込む案は採りません。共通identity・監査を持ち、kind固有の表または厳格schemaを持ちます。Wiki本文が必要なitemだけPage UUIDへ関連付けます。全メールを自動でPageにする必要はありません。
## 正本を一つ選ぶ
コレクションごとに `local_authoritative`、`remote_readonly`、将来の `remote_sync` を区別します。最初はlocalまたは読取専用mirrorです。remoteを正本とする項目の編集は、無断でlocal版を作るのではなく、未対応または明示的なcopyとして扱います。
同期を導入した場合もremote IDとWiki Pathを同一identityにしません。renameはbookmark/DAVのresource identityを再生成する理由になりません。
## 変更と同期の契約案
変更には期待versionとrequest_idを要求し、item更新・監査・outboxを同一transactionにします。connectorsは小さなbatchで取得し、保存成功後にcheckpointを進めます。再試行は重複排除し、失敗した一件のせいで全件再取り込みしません。
削除はtombstoneとして配送可能な期間を持たせます。画面から消したこと、mirror cacheを削除したこと、外部原本を削除したことを区別します。時計だけのlast-write-winsで予定やタスクを無言で上書きしません。
## 接続安全性
Domain、Principal、provider、許可host、credential purposeを固定します。リダイレクトとDNS再解決も検証し、無制限の内部ネットワーク取得を防ぎます。秘密はsecret_refだけを設定・ログへ載せます。接続解除はtoken失効、job停止、cache保持・削除の選択を伴います。
## UI案
一覧はcompact table、詳細はdrawerまたはdialog、設定は歯車。外部由来・最終同期・未送信変更・競合を区別して表示します。オフラインを「空の予定」と扱いません。Wiki保存時は保存先、出典、添付、公開予定の確認を一つの画面で行います。
## 受け入れ条件と未決事項
rename後もitem identity維持、権限失効で次要求から不可視、二重配送で重複なし、同期停止時の未送信保護、個人設定のDomain越境拒否を必須にします。共通itemを独立Object kindにするか拡張表に留めるかはprototypeで決め、DB migrationはその後です。
+53
View File
@@ -0,0 +1,53 @@
# 共通outbox:購読・移行・復旧契約
更新日:2026-09-25。単一インスタンスのSQLiteと既存イベントキューでの初期実装です。タスクの期限日/計画日通知は[正本と同時に作る予約](task-reminders.md)から配信します。outbox購読による汎用変更通知、分散配送、outboxの自動削除は未実装です。
## 責務を分ける
| 要素 | 役割 |
| --- | --- |
| `activity_outbox` | 正本変更と同時に保存する小さなイベント。Domain-local sequence、UUID、型、actor、対象、一意キー |
| `activity_outbox_heads` | Domain・イベント型ごとの最新sequence。INSERT triggerで同じtransaction内に更新 |
| `activity_outbox_checkpoints` | consumer・Domainごとの完了位置。成功後にのみ単調に進める |
| `event_jobs` | 実際の実行・再試行・優先度・ログ・キャンセル。outboxの記録とは別 |
`status`、`attempts`、`next_attempt_ms` 等のoutbox旧列は互換のため残しますが、consumer配信の完了や再試行判定には使いません。旧 `processed` 行も、新規consumerにとっては未処理になり得ます。`CompleteActivityOutboxThrough` は指定したconsumerのcheckpointのみ更新します。
## 購読と負荷
`ActivitySubscription` のconsumer IDとevent type集合は信頼するworkerコードで定義します。HTTP入力から任意の購読を生成しません。現在のCity購読は `page.created`、`revision.created`、`path.renamed`、`path.unlinked`、`object.deleted` です。タスク変更や無関係の拡張イベントだけではCityジョブを作りません。
未処理Domainの発見はheadsとcheckpointの比較で行い、全イベント履歴を毎回検索しません。1回最大100 Domain。イベント取得は型ごとにsequence索引から上限件数を取り、その結果をマージします。1回の最終結果は最大500件、型は最大16種類です。無関係のイベントが大量に入っても、対象イベントの手前を何ページも読み飛ばしません。
同じconsumer IDのまま購読型を増やすと、checkpointより古い新購読型のイベントを取り逃がします。**購読集合の変更時は新しいconsumer IDを使う**ことを契約とします(例:`notifications.tasks.v2`)。再生の開始位置・過去通知の抑止を別途指定します。
Cityは取得した対象イベントの最終sequenceまで、再構成成功後にcheckpointを進めます。並行して追加された後続イベントは次回に残ります。再構成後・checkpoint保存前の停止は再実行になりますが、既存の冪等な再構成で回復します。途中で失敗したbatchの一部だけを成功扱いにしてはいけません。
## タスクの直接接続と既存データ
タスクhead・版・専用ジャーナル・共通outbox・headsを同じtransactionで保存します。どこか一つが失敗したらDBの変更は全体をrollbackします。CASファイルの孤立可能性は従来どおりで、未commitのheadには現れません。
タスクの一意キーはDomainにスコープされた `organizer:{kind}:{uuid}:{version}`。payloadは版番号と変更時刻のみです。作成の再送、旧記録の再生、ジョブ再試行で二重記録しません。
`organizer_activity_bridge` は専用ジャーナルの移行位置です。`task.activity.publish` は1回100件、3秒timeout、既定60秒間隔・priority -5。処理したイベントと移行位置を同時commitします。失敗時は位置を進めません。対象が欠損して種類を判定できない場合はエラー停止し、黙ってスキップしません。タスクの物理削除導入時にはtombstoneを追加する必要があります。
この移行ジョブは拡張のユーザー操作を実行するものではなく、保存済み変更記録の内部保全です。拡張の無効化とは別に、イベント定義のenabledをOFFにできます。既存enabled・intervalの設定は起動時に保持します。`/_/api/v1/event/run` からも既存の管理権限で手動実行できます。ログは件数のみで、個人タスクのタイトルや本文は出しません。
## アップグレードと保全
初回のみ旧outboxを集計してheadsを作成します。この移行と完了マーカーはtransaction内で行い、途中失敗は再実行できます。次回以降の起動で履歴全件を再集計しません。既存checkpointと旧processed行は保持します。
新しいsequenceの採番は保持されたheadsの最大値から行います。将来の履歴整理でsequenceが巻き戻らないための対策ですが、**outboxの自動削除機能を提供するものではありません**。削除可能範囲には全必須consumerの完了確認に加えて、一意キーの再送抑止用tombstoneが必要です。heads・checkpoint・移行位置・正本DBをまとめてバックアップします。
## 残タスク
- [x] タスクの期限日/計画日通知:正本transactionで予約を更新し、配信時に現在権限・版を再検査。旧outboxイベントから予約を復活させない。
- [ ] 汎用の変更通知consumerと購読設定。
- [ ] consumer別の未処理/失敗表示、再生操作、購読変更時のbootstrap。
- [ ] 多数の失敗Domainがある場合の公平なdispatch、consumer別backoff/dead-letter。
- [ ] Outbox保持ポリシー:必須購読者の進捗、sequenceと一意キーの保全、consumer廃止手続き。
- [ ] 分散lease/fencing。現時点でHA時のexactly-onceを保証しない。
## テスト
購読者間の独立、型での絞り込み、ページング、旧processed行の取得、初回移行/再起動、transaction rollback、無関係イベント1200件の中の対象取得、sequence巻き戻り防止を検証します。サーバー側では、タスク変更でCityジョブが作られないこと、ページ変更では作られること、タスク保存全体のrollback、移行の再開/重複抑止、管理者の停止・間隔設定保持を検証します。運用DB・外部カレンダーは使用しません。
+36
View File
@@ -0,0 +1,36 @@
# 1. 設計思想と責務の分離
状態:基盤は実装済み。拡張への適用は継続中。
## 知識の住所と実体を分ける
PagesWikiは、人には階層と街の案内図を提供し、内部では同じ知識を複数の場所から参照できるシステムです。ファイルシステムのコピーをWikiの基本単位にはしません。
| 層 | 責務 | 他の層と混同しないもの |
| --- | --- | --- |
| Campus | ドメイン群の管理・配置・管理方針 | 記事本文の自動複製 |
| Domain | FQDN、Path名前空間、設定、権限評価 | インスタンスそのもの |
| Quartier / Street / Spot | 知識の整理・案内・管理範囲 | Pageの永続ID |
| Page | 言語や表示形式に依存しない知識の実体 | Path、ファイル名 |
| Revision | Pageの不変な版、言語、内容参照 | 最新版を指す可変名 |
| Document | SHA-256で識別する不変バイト列 | 認可情報 |
| Projection | 表示・編集・印刷・検索等の表現 | 別のPage正本 |
## 守る不変条件
- `(domain_uuid, path)` が意味上の住所。名前変更してもPage UUIDを変えない。
- Page UUID、Revision UUID、Document SHA-256は別物。ハッシュを知っていても読めるとは限らない。
- 同じPageを複数箇所で紹介しても、Revision履歴を複製しない。
- 言語はRevisionの属性。通常のPathに `/ja/` と `/en/` を強制しない。
- 閲覧・編集・公開・管理・委譲は別の許可。ログイン成功だけで本文権限を与えない。
- コメント、既読、評価、タスク状態はHTMLへ隠しフィールドとして埋め込まず、型付きメタデータとして持つ。
## 正本・派生データ・外部コピー
正本の更新と重要なメタデータはトランザクションで確定させます。検索索引、サムネイル、ランキング、通知は派生データとして再構築可能にします。外部メールやRSSの取り込みでは、外部の原本とWikiへの明示的なコピーを区別します。
現在、全書き込みが共通outboxへ接続されているわけではありません。「イベント化すべき」という設計契約を実装済みと読み替えてはいけません。
## 変更の受け入れ基準
機能ごとに、名前変更、権限失効、再試行、停止・再起動、大きな入力、外部障害を試験します。上限超過時に無制限処理や無認可表示へ切り替えません。通常の閲覧・保存を重いバックグラウンド処理より優先します。
+53
View File
@@ -0,0 +1,53 @@
# 6. 公開・承認・共有・匿名ナビゲーション
状態:明示的なRevision公開、Street/Spotの自動公開、匿名ナビゲーションは実装済み。承認者Inboxは受信者単位の保存・既読APIまで実装済みで、承認要求の生成・決裁UI・配送ワーカーはTODO。共有URL管理もTODO。
## 三つの異なるもの
1. 公開可能な上限:上位管理者が許可するaudience。下位は狭められるが広げられない。
2. 実際の公開:特定Revisionの明示承認、または確認済みの自動公開ルール。
3. 認証後のread/write:ユーザー・グループの権限。公開設定を変更しただけで編集者を増やさない。
`public` という上限を保存しただけで配下全部を公開したと扱いません。
## 現行の自動公開
| モード | 動作 |
| --- | --- |
| inherit | この階層ではルールを追加せず上位に従う |
| required | この範囲と配下は手動公開のみ。下位の自動公開で解除できない |
| automatic | Street/Spotの現在と将来の対象Page、および各言語の現在headを公開 |
Domain・Quartierもrequiredの上限制約を設定できます。automaticは有効な公開audienceを必要とし、影響プレビューと明示確認、policy/topology/versionの一致で有効化します。空の範囲にも設定できるため、今後作成する記事も対象になり得ます。
固定したPath境界のrename、設定した本人の権限失効、Domain/Campus無効化は公開を継続する根拠になりません。境界内への移動も対象になり得るため、importやメールコピーでは公開先の確認が重要です。別名、制限された子範囲、予約領域は現行の除外対象です。
自動公開の停止と、別途承認したRevisionの撤回は同じ操作ではありません。完全に非公開へ戻す場合はaudienceも制限します。新しい導入・migrationで自動公開を有効にしません。
影響確認は現在512 Path、ルール列挙128行、公開ナビゲーション20,000件/4 MiB等の上限があります。大きい範囲は分割・ページ送り付き確認の実装が必要です。上限超過を認可成功として扱いません。
## 匿名表示と共有リンク
公開Pageは読めるchildren・tree・City・パンくずへ移動できます。構造上必要な仮想親フォルダは、非公開の親本文やタイトルを見せる許可ではありません。通常・詳細・アイコン表示を共通化します。公開画面にダウンロード操作を強調する必要はありません。
ユーザー領域 `/u/{username}` はCityの通常公開から除外したまま、専用の公開設定を `/u/{username}/_/edit` に実装しています。プロフィール情報、プロフィール画像、ユーザーWikiのroot、配下の既定値をそれぞれ `private` / `domain` / `public` から選べます。配下の個別Pathは既定値より狭い範囲に限って上書きでき、その指定はsubtreeにも効きます。Domainの公開上限がpublicで、有効なCampus/Domainかつ認可がenforcingの場合だけpublicを保存・配信できます。上限を閉じれば次の要求から匿名配信も閉じます。
これは所有者が明示的に有効化する現在headの自動公開です。通常Pageの固定Revision承認を流用せず、将来の編集も同じ範囲で公開されます。匿名children・tree・browserは当該ユーザー領域だけの公開snapshotを使用し、グローバル匿名treeへ `/u/` を混ぜません。別名を持つObject、UUID/Revision経由、予約 `/_/` 経路では迂回できません。詳細は [user-space visibility contract](../user-space-publication.md) を参照してください。
将来のshare URLは期限・範囲・目的を限定した単一ページ表示が基本です。ログインセッションや公開ナビゲーション全体への昇格はさせません。Macaroonを含む委譲方式は設計段階で、予約 `/s/` があることは実装済みを意味しません。
## 承認Inboxの設計と実装状況
承認要求は対象Revision、依存物、scope、policy version、要求者と期限を固定します。変更された本文に旧承認を流用しません。承認者の現在の権限を決裁時に再検査し、outboxから通知Inboxへ重複排除して配送します。
状態はdraft → requested → approved / rejected / expired / supersededを案とします。取り消し・公開撤回は別監査イベントです。上位の承認必須設定を下位が解除できないこと、自動公開との優先順位、本人承認の可否を実装前に確定します。
共通通知Inboxの第一段階として、`notification_inbox`にDomain・受信者・イベント・種別を保存し、同じ組合せを重複排除します。`GET /_/api/v1/notifications` は現在のPrincipalに限定して `unread`、`limit`、`before` のkeyset取得を行い、`POST/PATCH /_/api/v1/notifications/read` は同じDomain・受信者の通知だけを既読化します。通知は権限や承認を付与せず、本文や秘密を保存しません。承認要求からの生成と再表示時の権限再検査は次段階です。
承認要求の対象(Path/Object/RevisionのハッシュとJSON)、policy version、generation、期限、要求者を`publication_requests`に固定保存し、決裁履歴を`publication_decisions`へ追記します。期限付きpending要求はスケジューラが小さなbatchでexpiredへ遷移させます。レビュアーの現在権限を再検査する決裁APIとInbox UIは、まだ公開していません。
認証済みのDomain管理者向けに、`POST /_/api/v1/publication/requests`でboundedな対象manifestを登録できます。idempotency keyで再送をまとめ、指定されたレビュアーがDomain管理権限を持つ場合だけInbox通知を作成します。`POST /_/api/v1/publication/requests/{uuid}/decisions`はDomainとgenerationを再検査し、承認・拒否をCASで一度だけ適用します。上位方針の継承、定足数、対象Revisionの現在性検査は、公開運用へ進む前の残タスクです。
## TODO
依存Assetと別名の完全な影響レビュー、広域の移動・統合時のfence、ルールGC、承認者・定足数・Inbox、署名付きpolicy配信、share失効管理。RSS読者や外部SNSが既に取得したコピーを遠隔削除できるとは約束しません。
+32
View File
@@ -0,0 +1,32 @@
# 料理レシピ管理(RECIPE)
状態:設計TODO。通常のWiki文書を置き換えず、Document/Revisionを正本として
レシピ用の構造化メタデータと表示Projectionを重ねる。
## 基本モデル
- レシピUUID、タイトル、概要、作者、出典、タグ、料理ジャンル、公開範囲。
- 材料は名称・数量・単位・任意の代替材料・アレルゲンを持つ。
- 手順は順序、本文、所要時間、温度、器具、画像Asset参照を持つ。
- 分量(何人分)、準備時間、調理時間、合計時間、難易度を分離する。
- Revisionと同じく変更履歴・差分・権限・監査を持ち、公開承認を迂回しない。
## 表示と編集
材料の人数倍・縮小、単位変換、買い物リスト化は表示時の派生値とし、正本の
数量を破壊しない。Markdown/HTML本文からの移行はpreviewと警告付きで行い、
未知の単位や曖昧な数量は文字列として保持する。画像・動画・PDFのAssetは
既存のMIME/権限処理を再利用し、本文への埋め込みは安全なProjectionを通す。
## 連携と拡張
JSON-LD Recipe、印刷用カード、買い物リスト、カテゴリ・材料検索を候補とする。
外部レシピサイトやメールからの取り込みは、出典URL・取得時刻・著作権表示を
保持し、無断公開や大量取得を行わない。栄養計算は外部データの版と不確実性を
表示し、医療上の助言とは扱わない。
## 受け入れ条件
単位変換で丸め誤差を明示すること、権限フィルタ後の検索結果だけを表示すること、
Revision競合・削除・Asset失効を再現できるfixtureを用意すること、共有時に作者・
出典・公開範囲を再確認することを条件とする。
+63
View File
@@ -0,0 +1,63 @@
# 20. 実装順序と受け入れ条件
状態:2026-09-19再整理。旧Phase番号は原ロードマップとの対応用に残し、実装は依存関係とリスク順に進めます。
## 優先順
2026-09-27追記:`organizer.tasks 0.11.1`で[既定タスクリスト名の変更](task-dav-default-list-name.md)を実装し、12:51 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-default-task-list-name.md)。PROPPATCH 405を解消し、利用者・domain別の表示名を保存、全探索結果へ反映する。実機再試行は確認待ち。色・アイコン・通常プロジェクトのPROPPATCHは別件。
2026-09-27追記:`organizer.tasks 0.11.0`の[タスク所属統一と上書き同期](task-dav-project-unification.md)を実装し、12:18 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-task-unification.md)。全Webプロジェクトを個別CalDAVリストとして公開し、既定リストはプロジェクトなしに限定。無条件PUT/DELETEはトークン別設定なしで受理し、版履歴を保持する。実機再同期は確認待ち。次の優先タスクは競合候補の保存、Inbox通知、上書き前/受信版の比較・採否選択(同文書のTODO)。反映時に観測したスケジューラclaimの一時的DBロックとディスク容量整理も運用記録へ残した。
2026-09-25追記:個人タスクCalDAV `0.8.0`を実装・隔離試験済み(2026-09-26 00:24 JST本番反映済み)。専用資格情報UI、VTODO、CLI双方向同期。制約と次段階は[タスクCalDAV](task-caldav.md)に整理。
2026-09-26追記:[予定・タスク共通CalDAV](caldav-common.md)を実装。共通principal/scope付き資格情報/VEVENT・VTODO探索・CLI同期/両画面の共通設定UI。chroncal実行試験とWeb回帰を実施。後続はTZID/VTIMEZONE等のlossless書込、sync-token、資格情報ごとのcalendar制限。反映状況は運用記録を参照。
2026-09-27追記:[OneTaskのOPTIONS判定互換モード](caldav-onetask-compatibility.md)を資格情報単位で実装、10:01 JSTに本番反映。OneTask実機の全操作確認は残件。通常モードは維持し、未対応データを黙って変換しない。
2026-09-27追記:[VTODOの複数タスクリスト](caldav-task-lists.md)を`organizer.tasks 0.10.0`として実装。OneTaskのMKCALENDAR失敗に対応し、リストをWebプロジェクトへ対応付ける。隔離試験では新規作成、リスト別CRUD、権限分離、索引復旧、Web所属変更、chroncalの名前付きリスト同期まで確認。後続:OneTask実機の再同期、PROPPATCH/リストDELETE、時刻付き期限・繰り返し・アラーム、差分同期。反映状況は[運用記録](../../operations/deployments/2026-09-27-task-lists.md)を参照。
| 優先 | 作業単位 | 前提 | 完了条件 |
| --- | --- | --- | --- |
| P0-1 | 認可transaction fence | typed target、現行認証 | revokeと同時更新の拒否、全変更経路の棚卸し |
| P0-2 | 公開影響と構造変更 | inert HTML、現行公開 | alias/依存/移動/統合で公開を無断拡張しない |
| P0-3 | identity lifecycle | 現行Principal/group | 外部連結、メール所有、最後の管理者保護 |
| P1-1 | 共通outbox | actor・Domain sequence | 正本との原子性、二重配送、checkpoint復旧 |
| P1-2 | City/directory局所化 | 所属モデル、索引 | 部分取得、手動編集保持、boundedなreconcile |
| P1-3 | 検索・decode・大容量 | 現行上限と測定 | current-only検索、隔離、stream、cancel |
| P2-1 | 通知と承認Inbox | P0、outbox | 現在権限で再表示・決裁・失効 |
| P2-2 | HTMLパーツ | round-trip fixture | macro/asset/未知HTMLを壊さない |
| P2-3 | local task | extension契約、原子的ジャーナル | 個人タスク/プロジェクト・Inbox通知・個人local時間枠・永続化Pomodoro・Todayの見積/時間枠/集中集約を実装済み。次は計画持ち越し、日課、共有 |
| P2-4 | RSS読取・Wiki保存 | connector共通部 | FreshRSS fixtureと安全なcopy |
| P2-6 | 料理レシピ管理 | Document/Asset、検索、権限 | 材料・分量・手順・調理時間・人数・タグを構造化し、単位変換と安全な共有を検証 |
| P3 | calendar/contact/mail | import/secret/競合契約 | read-only同期、明示copy、障害復旧 |
| P4 | 外部書込・DAV提供・HA | 運用選択、試験環境 | 双方向競合、fencing、復旧訓練 |
| P2-5 | CSV表macro・ODS境界 | projection/asset権限 | RFC4180 fixture、行列上限、Revision競合、safe fallback |
| P3-2 | Slide projection/editor | adapter manifest、CSP | Reveal互換preview、CSS-only編集、HedgeDoc/Slidev隔離 |
| P3-3 | IPAM・DNS・資産管理 | typed entity、承認Inbox、outbox | 重複検査、dry-run/apply監査、外部同期差分、soft delete |
P2以降の順序は利用価値で入れ替え可能ですが、P0の該当安全条件と共通outboxを省略しません。read-only prototypeは、本番への外部送信や公開を伴わない隔離fixtureで並行検証できます。
## 既に使える機能と残り
2026-09-25追加(0.7.0、2026-09-25 07:07 JST本番反映済み):[日別計画・持ち越し・親子グループ・Wikiメモ](task-daily-notes.md)。期限を変えない再割当て、親子cursor・補足親、初期Wiki本文とタスク紐づけの原子的作成を実装。日別キャパシティ・一括計画・共有は残件。
2026-09-25追記(同日05:59 JSTに本番反映済み):タスクのインライン編集、2階層サブタスク、月別日割り工程表、ホーム/Todayモーダル、Inboxのアクティブ通知、スマホカレンダーUIを実装・fixture検証。[タスク一覧の契約](task-inline-schedule.md)、[通知とWeb Pushの契約](active-notifications.md)、[スマホカレンダー](calendar-mobile.md)に上限・安全条件・実機確認の残件を記載。
- アドレス・不変Revision・Document・Asset:基本実装あり。保持・大容量・外部backendが残り。
- Campus/Domain・manifest:基本実装あり。反映ACK、PSK権限同期、DRが残り。
- City Map:実装あり。局所取得、reconcile所有権、生成品質が残り。
- 認証・グループ:実装あり。全endpoint監査・identity lifecycleが残り。
- 匿名公開・children/tree/City:実装あり。大規模影響確認、share、承認Inboxが残り。
- ブログ・日記・公開射影・本文RSS:実装あり。遠隔射影、コメント、tDiary等が残り。
- オーガナイザー:カレンダーと限定CalDAV、個人タスク/プロジェクト・個別ONのInbox通知、個人local時間枠と永続化Pomodoroあり。[タスク実装契約](tasks-implementation.md)、[時間枠とPomodoro](task-planning-focus.md)参照。一般のカレンダー予定通知・共有・VTODO、RSS購読・IMAPは未実装。
- 全面WYSIWYG、native app起動、第三者runtime、vim.wasm改善:判断待ちまたは保留。
## 共通のDone
仕様状態、schema/migration、rollbackまたはforward-fix手順、認可拒否、権限失効、version競合、重複再送、payload/行数/時間/並列上限、cancel、i18n、アクセシビリティ、運用メトリクスをそろえます。
Go全体テストと必要なbrowser fixtureを実施し、実装済み表示とdeployment記録を別々に更新します。外部APIはmockのみでlive接続成功と報告しません。
## 設計タスク一覧
次章のADR-O1〜O8を採用判断の単位とします。TASK、TICKET、CAL、CARD、DAV、RSS、MAIL、EDITOR、CSV、SLIDE、IPAM、DNS、INV、RECIPEの各IDは詳細章のTODOと対応します。実装開始時に担当・受け入れfixture・依存issue・見直し日を付けます。規模や納期を根拠なしに確約しません。
+40
View File
@@ -0,0 +1,40 @@
# 9. イベント・キュー・リソース監視
状態:永続ジョブ、定期実行、再試行・ログ、背景リソース監視あり。共通outboxの
永続 envelope(Domain sequence、idempotency、retry state、pending取得)は実装済み。
正本変更との同一transaction接続はPage/Revision/Path/Objectの初期経路で実装済み。
2026-09-25:consumerごとのcheckpointとイベント型別取得、タスク/プロジェクトの同一transaction接続、個別ONのタスク期限日/計画日Inbox通知も実装済み。汎用変更通知の配送、outbox保持ポリシー、分散leaseはTODO。
イベントログは生ログとトレンド用bucketを分離する。`event_log_policies`で
イベント種別ごとの保持時間、集約開始時間、bucket幅、最大生ログ件数を指定し、
`event_log_buckets`には件数と最初・最後の時刻だけを保持する。生ログの削除は
稼働中に安全な条件付きDELETEで行い、workerが書き込み中にテーブルをDROPしない。
物理partitionの導入時もrename→新規作成→切替を原子的に行う。
## 責務
`/_/api/v1/event/` は実行する処理とタイミング、`/_/api/v1/queue/` は実行要求と状態を扱います。予定、実行中、結果、ログ、キュー設定を区別します。イベントは安全な型付き処理であり、ユーザー入力をそのままshell commandへ変換しません。
## 前景を優先する
サムネイル・PDF・archive解析等は背景処理へ送ります。ジョブの同時数、入力・出力、時間、再試行を制限し、通常要求の活動を見ながらclaimします。長い接続だけで背景処理が永久停止しないよう、最低限の進行枠も必要です。
今後はジョブ件数だけでなくCPU/メモリ重みを管理します。native decoderのhard memory limit、プロセス分離、cancel時の子プロセス停止は別の安全条件です。
## outboxの実装と残り
正本変更と `activity_outbox` を同一transactionで記録します。Domain sequence、event UUID、型と版、actor、対象UUID、idempotency keyを含めます。本文や秘密をすべて複写しません。[購読・移行・復旧契約](outbox-delivery.md)を参照してください。
配送はat-least-onceを前提に、consumerごとのcheckpointと重複排除を使います。処理成功後にcheckpointを進め、途中停止から再試行します。City、通知、検索、集計が個別のHTTP handler callbackへ散らばらないようにします。既存の個別journalがあるだけではこの配送契約の完成ではありません。
## 運用画面とリソース
実行モニタはリソースグラフ4列と現在実行中のジョブ。設定は歯車、手動更新はアイコン。完了ジョブは履歴・ログへ統合し、ログは選択時に読みます。履歴期間の既定は1時間で選択を保持します。
現在値の表示更新、グラフの表示更新、背景の保存間隔は異なる設定です。1秒表示にしても1秒ごとの永続化や精密な瞬間使用率を意味しません。ブラウザを閉じても保存イベントは続きます。以前の「60秒既定」という原資料だけを最新設定の根拠にしません。
I/Oはプロセスの累積read/write bytes差分を時間で割った値です。再起動・欠測・counter減少は0に補間しません。ホスト全体のIOPS、latency、コンテナ合算と混同しません。
## TODOと検証
重み付き予算、dead-letterと安全な再投入、分散lease/fencing、outbox、SNMPv3読取collector。停止中の欠測、長いViewer接続、重いPDF連発、ジョブ再送、log大量化でも閲覧を優先できることを測定します。
+44
View File
@@ -0,0 +1,44 @@
# 22. 原資料との対応と外部仕様
更新日:2026-09-19。原資料はリポジトリの `docs/design/` に残します。以下はWiki上のファイル配信URLではなく、ソース資料との対応表です。
## 原資料の分類
| 本書の章 | 原資料ファイル |
| --- | --- |
| 設計思想 | `arch.md`、`access-model.md`、`platform-extension-architecture.md` |
| アドレス・保存 | `address-model.md`、`uri.md`、`asset-model.md`、`data-cli.md`、`revision-language-model.md` |
| Campus・Domain | `campus-domain-model.md`、`domain-namespace-federation.md`、`federation-manifest-integrity.md` |
| City | `knowledge-city-model.md`、`city-immersive-map.md`、`city-organization-ui.md`、`city-read-integrity.md`、`city-review-and-reconciliation.md`、`city-worker-navigation.md` |
| 認証・権限 | `auth.md`、`auth-backend.md`、`authorization-groups.md`、`browser-request-security.md`、`campus-admin-revocation.md`、`object-authority-scope.md`、`oidc-verification.md`、`smtp-magic-link-hardening.md` |
| 公開・共有 | `locality-publication-ownership.md`、`locality-access-publication.md`、`automatic-publication.md`、`publication-approval-inbox.md`、`public-navigation.md`、`social-link-cards.md` |
| Viewer・Editor | `projection-adapters.md`、`html-projection-trust.md`、`projection-metadata-cache.md`、`home-bookmark-sections-vim.md` |
| ナビゲーション・import | `navigation-home-sidebar.md`、`configuration-panels.md`、`search-results.md`、`archive-import.md`、`path-mutation-integrity.md` |
| Scheduler・拡張 | `event-scheduler.md`、`system-extensions.md`、`platform-extension-architecture.md` |
| 日記・ブログ | `diary-blog-plugins.md` |
| 新規構想 | `organizer-and-editing-ideas.md`、本書第12〜17章 |
| 保全・性能 | `object-list-pagination.md`、`revision-listing.md`、`zombie-gc-integrity.md`、`implementation-status.md` |
| 多言語 | `i18n-delivery.md`、`revision-language-model.md` |
| 実装計画・履歴 | `implementation-roadmap.md`、`implementation-status.md`、`hardening-execution-2026-09.md` |
初期draft、詳細契約、実装状況、実行履歴は文書の用途が違います。仕様の全項目を実装済みと判定するためにdraftの文体を使わず、コードとテストの実装単位で確認します。
## 今回の照合対象の実装
`internal/store/automatic_publication.go`、`locality_publication.go`、`navigation.go`、`periodicals.go`、`public_periodicals.go`、`groups_inheritance.go`、`city_reference.go`、`revision_store.go`、`internal/server/periodical*.go`、`public_periodical*.go`、`internal/extensions/registry.go`、`data/pageswiki-cli` 等を、状態の混同が起きやすい箇所として確認しました。これは全実装の安全性監査を完了したという意味ではありません。
## 公式仕様と連携資料
以下は2026-09-19に確認した設計根拠です。プロトコル対応を実装する際は更新RFC・errata・選定clientの版も固定します。
- [RFC 5545 — iCalendar](https://www.rfc-editor.org/rfc/rfc5545)
- [RFC 4791 — CalDAV](https://www.rfc-editor.org/rfc/rfc4791)
- [RFC 6350 — vCard](https://www.rfc-editor.org/rfc/rfc6350)
- [RFC 6352 — CardDAV](https://www.rfc-editor.org/rfc/rfc6352)
- [RFC 6578 — WebDAV Collection Synchronization](https://www.rfc-editor.org/rfc/rfc6578)
- [RFC 9051 — IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)
- [RFC 4287 — Atom](https://www.rfc-editor.org/rfc/rfc4287)
- [FreshRSS — Google Reader compatible API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)
- [newsboat 2.42 — FreshRSS integration](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)
これらの仕様が存在することと、PagesWikiがその機能を提供することは別です。本書のモデル、MVP順序、table/API案はPagesWiki向けの設計提案として区別します。
Loaded 100 of 712 files, more files were not shown because too many files have changed in this diff. Show more