Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
c577dca
docs: record approved v18 compatibility preparation design
Innei Nov 8, 2026
ca5a297
feat(core): add compatible POST maintenance actions
Innei Nov 8, 2026
41d877f
feat(clients): prepare transport for v18 contracts
Innei Nov 8, 2026
5d5dc53
refactor(core): canonicalize legacy configuration at storage boundary
Innei Nov 8, 2026
b88a950
test(core): preserve concrete image-only provider fixture
Innei Nov 8, 2026
4510d08
refactor(core): derive AI metadata from generation metrics
Innei Nov 8, 2026
d123f3b
feat(core): add standalone v18 readiness diagnostics
Innei Nov 8, 2026
9a8b96f
fix(core): isolate upgrade CLI from application Vite transforms
Innei Nov 8, 2026
c954342
feat(core): prepare existing installations transactionally for v18
Innei Nov 8, 2026
e16210e
feat(core): rotate JWT secrets during explicit maintenance
Innei Nov 8, 2026
6b93520
docs(core): document and rehearse the v18 preparation phase
Innei Nov 8, 2026
d455552
fix(core): close preparation review safety and compatibility gaps
Innei Nov 8, 2026
c62cf18
fix(core): require truly empty application data for new-install readi…
Innei Nov 8, 2026
dde2289
docs: record verified v18 preparation outcome
Innei Nov 8, 2026
c42276e
fix(security): require encrypted storage and retire legacy writers
Innei Nov 8, 2026
565ebb9
docs(security): align deployments and upgrade guides with required en…
Innei Nov 8, 2026
b5eb3d0
fix(security): unwrap historical OAuth ciphertext before migration
Innei Nov 8, 2026
afb4d94
db: migrate legacy configuration in the release phase
Innei Nov 8, 2026
40cb6f0
feat(config): remove runtime legacy configuration compatibility
Innei Nov 8, 2026
d8debe9
fix(config): preserve raw configuration and sibling credentials durin…
Innei Nov 8, 2026
c9d7baa
refactor(db): move shared migration helpers out of upgrade
Innei Nov 8, 2026
665a0d6
refactor(db): consolidate v18 preparation into release migrations
Innei Nov 8, 2026
8f0f90f
fix(configs): preserve schema field casing in admin settings
Innei Nov 8, 2026
eea9e2f
docs: record admin settings acceptance
Innei Nov 8, 2026
162517d
feat(core)!: remove encryption algorithm selection
Innei Nov 8, 2026
988ff35
feat(core): persist automatic development encryption keys
Innei Nov 8, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 5 additions & 8 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# THIS ENV FILE EXAMPLE ONLY FOR DOCKER COMPOSE
# SEE https://docs.docker.com/compose/environment-variables/#the-env-file
JWT_SECRET=asffasgvxczfqreqw213
# Required: a private JWT secret of at least 32 characters. Preserve an existing value.
JWT_SECRET=
ALLOWED_ORIGINS=innei.ren,www.innei.ren

# Must be 64 hexadecimal characters. Keep the existing key when upgrading.
ENCRYPT_KEY=593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab
# Temporary legacy plaintext escape hatch; v18 will require encryption.
ENCRYPT_ENABLE=false
# Required: 64 hexadecimal characters. Keep the existing key when upgrading.
# New instances only: openssl rand -hex 32; persist this value before starting.
ENCRYPT_KEY=

# Comma-separated HTTPS origins that mx-core may contact for Push Relay.
MX_PUSH_RELAY_ORIGINS=
Expand All @@ -21,6 +21,3 @@ PG_URL=
# Throttle
THROTTLE_TTL=10
THROTTLE_LIMIT=20

# Enable only after every replica has the compatible secret reader; see docs/security-secret-storage.md
MX_SECRET_STORAGE_V2=false
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,9 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Test
env:
JWT_SECRET: test-docker-jwt-secret-at-least-32-characters
MX_ENCRYPT_KEY: '593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab'
run: |
bash ./scripts/workflow/test-docker.sh
sudo rm -rf ./data
Expand Down Expand Up @@ -121,7 +124,8 @@ jobs:
PG_DATABASE: mx_core
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
JWT_SECRET: test-bundle-server-jwt-secret
JWT_SECRET: test-bundle-server-jwt-secret-at-least-32-characters
MX_ENCRYPT_KEY: '593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab'
MIGRATIONS_DIR: ${{ github.workspace }}/apps/core/src/database/migrations

e2e:
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,8 @@ jobs:
PG_DATABASE: mx_core
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
JWT_SECRET: test-bundle-server-jwt-secret
JWT_SECRET: test-bundle-server-jwt-secret-at-least-32-characters
MX_ENCRYPT_KEY: '593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab'
MIGRATIONS_DIR: ${{ github.workspace }}/apps/core/src/database/migrations
run: |
bash scripts/workflow/test-server.sh
Expand Down
6 changes: 3 additions & 3 deletions apps/admin/src/api/aggregate.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { ContentDocument, DraftModel } from '~/models/draft'

import type { RecentActivities } from './activity'
import { getJson } from './http'
import { getJson, requestJson } from './http'

export interface StatCount {
allComments?: number
Expand Down Expand Up @@ -180,9 +180,9 @@ export function getSiteLikeCount() {
}

export function cleanCache() {
return getJson<void>('/clean_catch')
return requestJson<void>('/clean_catch', { method: 'POST' })
}

export function cleanRedis() {
return getJson<void>('/clean_redis')
return requestJson<void>('/clean_redis', { method: 'POST' })
}
2 changes: 1 addition & 1 deletion apps/admin/src/api/backups.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ export async function getBackups() {
}

export function createBackup() {
return requestBlob('/backups/new')
return requestBlob('/backups/new', { method: 'POST' })
}

export function downloadBackup(filename: string) {
Expand Down
7 changes: 5 additions & 2 deletions apps/admin/src/api/health.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { getJson } from './http'
import { requestJson } from './http'

export function sendTestEmail() {
return getJson<{ message?: string; trace?: string }>('/health/email/test')
return requestJson<{ message?: string; trace?: string }>(
'/health/email/test',
{ method: 'POST' },
)
}
67 changes: 67 additions & 0 deletions apps/admin/src/api/options.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import { afterEach, describe, expect, it, vi } from 'vitest'

import { type ConfigFormSchema, getAllOptions } from './options'

afterEach(() => vi.unstubAllGlobals())

describe('settings values and form schema', () => {
it('restores declared acronym keys after wire camelization so fields display and save the existing values', async () => {
vi.stubGlobal(
'fetch',
vi.fn(
async () =>
new Response(
JSON.stringify({
data: {
comment_upload_options: {
single_file_size_mb: 7,
reader_total_active_bytes_mb: 70,
enable: true,
},
opaque: { customField: { APIKey: 'preserved' } },
},
}),
{ status: 200, headers: { 'content-type': 'application/json' } },
),
),
)
const schema: ConfigFormSchema = {
title: 'Settings',
defaults: {},
groups: [
{
key: 'storage',
title: 'Storage',
description: '',
icon: 'database',
sections: [
{
key: 'commentUploadOptions',
title: 'Comment uploads',
fields: [
{
key: 'singleFileSizeMB',
title: 'File limit',
ui: { component: 'number' },
},
{
key: 'readerTotalActiveBytesMB',
title: 'Total limit',
ui: { component: 'number' },
},
],
},
],
},
],
}
expect(await getAllOptions(schema)).toEqual({
commentUploadOptions: {
singleFileSizeMB: 7,
readerTotalActiveBytesMB: 70,
enable: true,
},
opaque: { customField: { APIKey: 'preserved' } },
})
})
})
34 changes: 32 additions & 2 deletions apps/admin/src/api/options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,38 @@ export interface UpdateOwnerData {
username?: string
}

export function getAllOptions() {
return getJson<SystemOptions>('/options')
function restoreFormFieldKeys(
value: unknown,
fields: ConfigFormField[],
): unknown {
if (!value || typeof value !== 'object' || Array.isArray(value)) return value
const source = value as Record<string, unknown>
const keys = new Map(
Object.keys(source).map((key) => [key.toLowerCase(), key]),
)
const result = { ...source }
for (const field of fields) {
const key = keys.get(field.key.toLowerCase())
if (key === undefined) continue
result[field.key] = field.fields?.length
? restoreFormFieldKeys(source[key], field.fields)
: source[key]
if (key !== field.key) delete result[key]
}
return result
}

export async function getAllOptions(schema?: ConfigFormSchema) {
const options = await getJson<SystemOptions>('/options')
if (!schema) return options
const result = { ...options }
for (const group of schema.groups)
for (const section of group.sections)
result[section.key] = restoreFormFieldKeys(
options[section.key],
section.fields,
)
return result
}

export function getFormSchema() {
Expand Down
40 changes: 40 additions & 0 deletions apps/admin/src/api/upgrade-compatibility.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
import { afterEach, describe, expect, it, vi } from 'vitest'

import { cleanCache, cleanRedis } from './aggregate'
import { createBackup } from './backups'
import { sendTestEmail } from './health'

describe('maintenance transport', () => {
afterEach(() => vi.restoreAllMocks())

it.each([
['/clean_catch', cleanCache],
['/clean_redis', cleanRedis],
['/health/email/test', sendTestEmail],
] as const)('posts authenticated action %s', async (path, action) => {
const request = vi
.spyOn(globalThis, 'fetch')
.mockResolvedValue(new Response(null, { status: 204 }))
await action()
expect(String(request.mock.calls[0][0])).toMatch(new RegExp(`${path}$`))
expect(request.mock.calls[0][1]).toMatchObject({
method: 'POST',
credentials: 'include',
})
})

it('posts backup creation and retains the downloaded bytes', async () => {
const bytes = new Uint8Array([0, 255, 80, 75])
const request = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
new Response(bytes, {
headers: { 'content-type': 'application/octet-stream' },
}),
)
const result = await createBackup()
expect(new Uint8Array(await result.arrayBuffer())).toEqual(bytes)
expect(request.mock.calls[0][1]).toMatchObject({
method: 'POST',
credentials: 'include',
})
})
})
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ export function SystemSettings(props: {

const optionsQuery = useQuery({
enabled: Boolean(props.schema),
queryFn: getAllOptions,
queryFn: () => getAllOptions(props.schema),
queryKey: adminQueryKeys.settings.options(),
})

Expand Down
26 changes: 22 additions & 4 deletions apps/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@ pnpm test:watch # watch mode

| Variable | Description | Default |
|----------|-------------|---------|
| `JWT_SECRET` | Secret for JWT signing | Required |
| `JWT_SECRET` | Explicit secret for JWT signing and OAuth encryption, at least 32 characters | Required |
| `ALLOWED_ORIGINS` | CORS allowed origins (comma-separated) | — |
| `PG_URL` | Full PostgreSQL connection string | — |
| `PG_HOST` | PostgreSQL host | `127.0.0.1` |
Expand All @@ -238,15 +238,18 @@ pnpm test:watch # watch mode
| `REDIS_PORT` | Redis port | `6379` |
| `REDIS_PASSWORD` | Redis password | — |
| `SNOWFLAKE_WORKER_ID` | Snowflake ID worker ID (0–1023) | Required |
| `ENCRYPT_ENABLE` | Enable field encryption; `false` is a temporary v17 plaintext escape hatch. Encryption is required starting in v18 | `false` |
| `ENCRYPT_KEY` | 64-char hex encryption key | — |
| `MX_SECRET_STORAGE_V2` | Enable new secret formats after all replicas are upgraded; see [rollout guide](../../docs/security-secret-storage.md) | `false` |
| `ENCRYPT_KEY` / `MX_ENCRYPT_KEY` | Required explicit 64-char hex field key; preserve the existing key | — |
| `ENCRYPT_ENABLE` / `MX_ENCRYPT_ENABLE` / `MX_SECRET_STORAGE_V2` | Deprecated: remove these flags. Old true values are ignored; false values refuse startup | — |
| `THROTTLE_TTL` | Rate limit window (seconds) | `10` |
| `THROTTLE_LIMIT` | Max requests per window | `100` |
| `PORT` | Server port | `2333` |
| `TZ` | Timezone | `Asia/Shanghai` |
| `DISABLE_CACHE` | Disable Redis caching | `false` |

On this unreleased branch, run the mandatory configuration data migration via `node migrate.mjs` before startup, after stopping all old replicas/background writers. Runtime configuration accepts only the current schema; retired sections and unknown declared fields are rejected. See the [migration guide](../../docs/v18-preparation.md).

Field encryption and V2 writes are mandatory; `JWT_SECRET` must have at least 32 characters. See the [upgrade guide](../../docs/v18-preparation.md) before deploying to an existing instance.

For managed Redis providers such as Upstash, pass the provider URI as
`REDIS_CONNECTION_STRING=rediss://user:password@host:port`. The `rediss://`
scheme enables TLS. If the provider exposes the same URI as `REDIS_URL`, it is
Expand Down Expand Up @@ -299,3 +302,18 @@ Inspired in part by [nodepress](https://github.com/surmon-china/nodepress).
---

Since 2021-08-31.

## Preparing for v18 (unreleased)

This branch adds standalone `upgrade:check` and `upgrade:rotate-jwt` tooling.
Configuration, credential and metric backfills run through the mandatory
release-phase `migrate` command. These changes are not in v17.0.4; a minimum
released preparation tag and client matrix will be recorded after release
verification. Legacy GET actions and SDK 5.x signatures remain, while this
branch requires encryption and canonical configuration. No columns are
dropped in this phase.

See the [preparation runbook](../../docs/v18-preparation.md) for read-only
diagnostics, release-phase migration, original-secret requirements
and offline JWT rotation. Do not change an existing encryption key or JWT
to fix decryption failures.
2 changes: 1 addition & 1 deletion apps/core/ecosystem.config.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ module.exports = {
watch: false,
instances: cpuLen,
max_memory_restart: '520M',
args: '--color --encrypt_enable',
args: '--color',
env: {
NODE_ENV: 'production',
NODE_PATH: nodePath,
Expand Down
3 changes: 2 additions & 1 deletion apps/core/ecosystem.dev.config.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
const { execSync } = require('node:child_process')

const nodePath = execSync(`npm root --quiet -g`, { encoding: 'utf-8' }).split(
'\n',
)[0]
Expand All @@ -13,7 +14,7 @@ module.exports = {
watch: false,
instances: 2,
max_memory_restart: '220M',
args: '--color --encrypt_enable',
args: '--color',
env: {
NODE_ENV: 'development',
NODE_PATH: nodePath,
Expand Down
7 changes: 3 additions & 4 deletions apps/core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,7 @@
"prebuild": "rimraf dist",
"build": "npm run bundle",
"dev": "cross-env NODE_ENV=development nodemon --signal SIGKILL --watch src --ext ts,json --exec \"vite-node src/dev.ts\"",
"dev:encrypt": "npm run dev -- --encrypt_enable --encrypt_key=33b9405ac49f63ef4ccbf6b338aeeff8152e844d942ef22278abbec2b1f93b5e",
"migrate": "vite-node src/migrate.ts",
"migrate:secrets": "cross-env MX_SECRET_STORAGE_V2=1 MX_MIGRATE_SECRETS=1 vite-node src/app-migrate.ts",
"migrate:app": "cross-env NODE_ENV=development vite-node src/app-migrate.ts",
"lint:migrations": "tsx --tsconfig tsconfig.json scripts/lint-migrations.ts",
"openapi:export": "vite-node scripts/export-openapi.ts",
Expand All @@ -45,7 +43,9 @@
"test:live:mix": "NODE_ENV=development RUN_LIVE_TESTS=1 SMOKE_TRANSLATOR_PROVIDER=openai-compatible SMOKE_REVIEWER_PROVIDER=openrouter SMOKE_REVIEWER_MODEL=openai/gpt-5.5 vitest run translation-review-pipeline.live.e2e-spec.ts",
"test:live:deepseek-mix": "NODE_ENV=development RUN_LIVE_TESTS=1 SMOKE_REVIEWER_MODEL=openai/gpt-5.5 vitest run translation-review-pipeline.live.e2e-spec.ts",
"docs": "npx @compodoc/compodoc -p tsconfig.json -s -d docs",
"publish": "bump"
"publish": "bump",
"upgrade:check": "vite-node --config vite.upgrade.config.ts src/upgrade.ts check",
"upgrade:rotate-jwt": "vite-node --config vite.upgrade.config.ts src/upgrade.ts rotate-jwt"
},
"bump": {
"before": [
Expand Down Expand Up @@ -132,7 +132,6 @@
"mime-types": "^3.0.2",
"mkdirp": "^3.0.1",
"nanoid": "6.0.2",
"node-machine-id": "1.1.12",
"nodemailer": "10.2.1",
"object-scan": "^20.0.4",
"octokit": "^5.0.5",
Expand Down
2 changes: 0 additions & 2 deletions apps/core/src/app.config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,8 @@ export const DEBUG_MODE = {
httpRequestVerbose: false,
}

export const SECRET_STORAGE_V2 = true
export const ENCRYPT = {
key: '593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab',
enable: true,
}

export const THROTTLE_OPTIONS = {
Expand Down
Loading
Loading