@fg-lab/amadeus-qq 0.0.0-stage → 1.2.1

package/scripts/release-audit.mjs

@@ -0,0 +1,59 @@
+import { execSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const pkg = JSON.parse(readFileSync('package.json', 'utf8'))
+const requirements = {
+  '@fg-lab/amadeus-qq': ['src/index.js', 'lib/client.js', 'src/console/index.html', 'src/console/console.js', 'src/console/console.css', 'cordis.patch.yml', 'preset.patch.yml'],
+  '@fg-lab/amadeus-memory': ['lib/index.js', 'lib/client.js', 'cordis.patch.yml', 'runtime-manifest.json'],
+  '@fg-lab/amadeus-life': ['src/index.js', 'lib/client.js', 'cordis.patch.yml', 'icon.svg', 'locale/zh.json', 'locale/en.json'],
+  '@fg-lab/amadeus-state': ['src/index.js', 'lib/client.js', 'cordis.patch.yml', 'icon.svg', 'locale/zh.json', 'locale/en.json'],
+  '@fg-lab/amadeus-persona': ['src/index.js', 'src/client.js', 'src/console/index.html', 'src/console/console.js', 'src/console/console.css', 'cordis.patch.yml']
+}
+for (const required of Object.values(requirements)) required.push('assets/market-icon.png', 'screenshots.json', 'docs/INSTALL_V1_2.md')
+if (pkg.license === 'MIT') requirements[pkg.name]?.push('LICENSE')
+const expectedId = pkg.name === '@fg-lab/amadeus-memory' ? 'dsh-mneme' : pkg.name.replace('@fg-lab/', '')
+const errors = []
+const warnings = []
+if (!requirements[pkg.name]) errors.push(`unexpected package name: ${pkg.name}`)
+if (pkg.scripts?.prepare || pkg.scripts?.postinstall || pkg.scripts?.install) errors.push('install-time script is forbidden for the prebuilt package')
+if (!pkg.dsh?.bundle?.patch || !pkg.dsh?.client) errors.push('missing DSH bundle patch or client manifest')
+if (!pkg.engines?.dsh) errors.push('missing tested engines.dsh range')
+if (!readFileSync('cordis.patch.yml', 'utf8').includes(`id: ${expectedId}`)) errors.push(`patch does not preserve plugin id ${expectedId}`)
+if (pkg.private === true) warnings.push('private:true prevents public npm publish')
+if (!pkg.license || pkg.license === 'UNLICENSED') warnings.push('public distribution license needs owner review')
+
+let manifest
+try {
+  const raw = execSync('npm pack --dry-run --json --ignore-scripts', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  const parsed = JSON.parse(raw)
+  manifest = Array.isArray(parsed) ? parsed[0] : parsed[pkg.name] ?? Object.values(parsed)[0]
+} catch (error) {
+  errors.push(`npm pack failed: ${error.stderr?.toString().trim() || error.message}`)
+}
+
+if (manifest) {
+  const names = new Set(manifest.files.map(file => file.path.replaceAll('\\', '/')))
+  for (const path of requirements[pkg.name] ?? []) if (!names.has(path)) errors.push(`missing runtime asset: ${path}`)
+  try {
+    const screenshots = JSON.parse(readFileSync('screenshots.json', 'utf8'))
+    if (!Array.isArray(screenshots) || screenshots.length < 1 || screenshots.length > 8) errors.push('screenshots.json must list 1–8 images')
+    else for (const path of screenshots) {
+      if (typeof path !== 'string' || path.startsWith('/') || path.includes('..') || !/\.(png|jpe?g|webp)$/i.test(path)) errors.push(`invalid screenshot path: ${path}`)
+      else if (!names.has(path)) errors.push(`screenshot is absent from package: ${path}`)
+    }
+  } catch (error) { errors.push(`invalid screenshots.json: ${error.message}`) }
+  const forbiddenName = /(^|\/)(?:node_modules|private|profiles|logs|\.git|\.env[^/]*|\.npmrc|credentials(?:\.json)?|secrets?)(?:\/|$)|^runtime\/|\.(?:db|sqlite(?:-wal|-shm)?|log|key|pem)$/i
+  const secret = /gh[pousr]_[A-Za-z0-9_]{30,}|(?:sk-|sk_)[A-Za-z0-9]{32,}|-----BEGIN (?:RSA|OPENSSH|EC) PRIVATE KEY-----|DEEPSEEK_API_KEY\s*[:=]\s*['"]?[A-Za-z0-9_-]{16,}/
+  for (const path of names) {
+    if (forbiddenName.test(path)) errors.push(`forbidden package path: ${path}`)
+    if (path === 'package.json') continue
+    const file = readFileSync(resolve(path))
+    if (file.length <= 2_000_000 && !file.includes(0) && secret.test(file.toString('utf8'))) errors.push(`possible credential in package file: ${path}`)
+  }
+  console.log(JSON.stringify({ name: manifest.name, version: manifest.version, files: names.size, unpackedBytes: manifest.unpackedSize, warnings }, null, 2))
+}
+if (errors.length) {
+  for (const error of errors) console.error(`ERROR ${error}`)
+  process.exitCode = 1
+}

package/scripts/symlink-security.mjs

@@ -0,0 +1,8 @@
+import {spawnSync} from 'node:child_process';
+if(process.platform!=='linux')throw Error('Run this release gate on Linux; Windows skips do not satisfy it');
+const files=['tests/audio-read.test.mjs','tests/media-read.test.mjs','tests/file-read.test.mjs','tests/outbound-media.test.mjs'];
+const result=spawnSync(process.execPath,['--test','--test-name-pattern=symlink',...files],{encoding:'utf8'});
+process.stdout.write(result.stdout??'');process.stderr.write(result.stderr??'');
+const cases=(result.stdout??'').split(/\r?\n/).filter(line=>/^(?:not )?ok \d+ - .*symlink/i.test(line));
+if(result.status!==0||cases.length!==4||cases.some(line=>!line.startsWith('ok ')||/# SKIP|# TODO/.test(line)))throw Error('All four symlink security cases must execute and pass without skips');
+console.log('RELEASE_GATE: 4 symlink safety tests executed and passed');

package/src/account-profile.js

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { snapshotControlledImage } from './outbound-media.js'
+
+const STATUS_VALUES = new Set([10, 30, 40, 50, 60, 70])
+const MAX_SIGNATURE = 200
+const MAX_NICKNAME = 36
+
+function profileError(code) {
+  const error = new Error(code)
+  error.code = code
+  return error
+}
+
+function cleanText(value, max, code) {
+  if (typeof value !== 'string') throw profileError(code)
+  const text = value.replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  if (text.length === 0 || text.length > max) throw profileError(code)
+  return text
+}
+
+function decimalId(value) {
+  const id = typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : value
+  if (typeof id !== 'string' || !/^[1-9]\d{0,19}$/.test(id)) throw profileError('QQ_PROFILE_RESPONSE_INVALID')
+  return id
+}
+
+function responseInvalid() {
+  return profileError('QQ_PROFILE_RESPONSE_INVALID')
+}
+
+function profileFingerprint(scene, action, payload) {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      account: scene.botId,
+      scene: scene.peerId,
+      action,
+      payload,
+    }))
+    .digest('hex')
+}
+
+export function createAccountProfile({ core, transport, authorize, ledger, sendRoot, tempRoot }) {
+  if (typeof authorize !== 'function') throw profileError('QQ_PROFILE_UNAUTHORIZED')
+  if (!transport || typeof transport.action !== 'function') throw profileError('QQ_PROFILE_UNAVAILABLE')
+
+  async function check(sessionId, action, write) {
+    let scene
+    try {
+      scene = core.authorizedScene(sessionId)
+    } catch {
+      throw profileError('QQ_PROFILE_UNAUTHORIZED')
+    }
+    if (write && scene.kind !== 'private') throw profileError('QQ_PROFILE_OWNER_REQUIRED')
+    let allowed = false
+    try {
+      allowed = await authorize({ action, write, sessionId, scene }) === true
+    } catch {
+      allowed = false
+    }
+    if (!allowed) throw profileError('QQ_PROFILE_UNAUTHORIZED')
+    return scene
+  }
+
+  async function call(action, params, write) {
+    let data
+    try {
+      data = await transport.action(action, params, 10_000)
+    } catch (error) {
+      if (!write) throw profileError('QQ_PROFILE_UNAVAILABLE')
+      if (error?.code === 'ONEBOT_REJECTED') throw profileError('QQ_PROFILE_REJECTED')
+      throw profileError('QQ_PROFILE_UNKNOWN')
+    }
+    if (data === null || data === undefined) {
+      if (write) return {}
+      throw responseInvalid()
+    }
+    if (typeof data !== 'object') throw responseInvalid()
+    return data
+  }
+
+  async function loginInfo(sessionId, write = false) {
+    const data = await call('get_login_info', {}, write)
+    return { userId: decimalId(data.user_id), nickname: typeof data.nickname === 'string' ? data.nickname.slice(0, MAX_NICKNAME) : '' }
+  }
+
+  async function strangerInfo(sessionId, userId, write = false) {
+    const data = await call('get_stranger_info', { user_id: userId, no_cache: true }, write)
+    return {
+      longNick: typeof data.long_nick === 'string' ? data.long_nick.slice(0, MAX_SIGNATURE) : '',
+      status: Number.isFinite(Number(data.status)) ? Number(data.status) : null,
+    }
+  }
+
+  async function userStatus(userId, write = false) {
+    const data = await call('nc_get_user_status', { user_id: userId }, write)
+    const status = Number(data.status)
+    const extStatus = Number(data.ext_status)
+    if (!Number.isSafeInteger(status) || !Number.isSafeInteger(extStatus)) throw responseInvalid()
+    return { status, extStatus }
+  }
+
+  async function readProfileInternal(sessionId, write = false) {
+    const login = await loginInfo(sessionId, write)
+    const stranger = await strangerInfo(sessionId, login.userId, write)
+    const online = await userStatus(login.userId, write)
+    return {
+      userId: login.userId,
+      nickname: login.nickname,
+      signature: stranger.longNick,
+      status: online.status,
+      extStatus: online.extStatus,
+    }
+  }
+
+  async function writeWithLedger(sessionId, action, payload, actionId, verify) {
+    const scene = await check(sessionId, action, true)
+    if (!ledger || typeof ledger.run !== 'function') throw profileError('QQ_PROFILE_LEDGER_REQUIRED')
+    if (typeof actionId !== 'string' || !/^[\w-]{1,100}$/.test(actionId)) throw profileError('QQ_PROFILE_ACTION_ID_INVALID')
+    const fingerprint = profileFingerprint(scene, action, payload)
+    return ledger.run({
+      actionId,
+      fingerprint,
+      action,
+      sessionId,
+      sceneKey: `${scene.botId}:${scene.kind}:${scene.peerId}`,
+      execute: async () => {
+        await call(action, payload, true)
+        try {
+          await check(sessionId, action, true)
+        } catch {
+          // The platform write already happened; do not report a clean failure.
+          throw profileError('QQ_PROFILE_UNKNOWN')
+        }
+        let profile
+        try {
+          profile = await readProfileInternal(sessionId, true)
+          if (!(await verify(profile))) throw profileError('QQ_PROFILE_UNKNOWN')
+        } catch (error) {
+          if (error?.code === 'QQ_PROFILE_UNKNOWN') throw error
+          throw profileError('QQ_PROFILE_UNKNOWN')
+        }
+        try {
+          await check(sessionId, action, true)
+        } catch {
+          throw profileError('QQ_PROFILE_UNKNOWN')
+        }
+        return profile
+      },
+    })
+  }
+
+  return Object.freeze({
+    async readProfile({ sessionId }) {
+      await check(sessionId, 'get_login_info', false)
+      const profile = await readProfileInternal(sessionId)
+      await check(sessionId, 'get_login_info', false)
+      return profile
+    },
+
+    async setSignature({ sessionId, signature, actionId }) {
+      const value = cleanText(signature, MAX_SIGNATURE, 'QQ_PROFILE_SIGNATURE_INVALID')
+      return writeWithLedger(sessionId, 'set_self_longnick', { longNick: value }, actionId,
+        profile => profile.signature === value)
+    },
+
+    async setNickname({ sessionId, nickname, actionId }) {
+      const value = cleanText(nickname, MAX_NICKNAME, 'QQ_PROFILE_NICKNAME_INVALID')
+      return writeWithLedger(sessionId, 'set_qq_profile', { nickname: value }, actionId,
+        profile => profile.nickname === value)
+    },
+
+    async setOnlineStatus({ sessionId, status, extStatus, batteryStatus, actionId }) {
+      if (!Number.isSafeInteger(status) || !STATUS_VALUES.has(status)) throw profileError('QQ_PROFILE_STATUS_INVALID')
+      if (!Number.isSafeInteger(extStatus) || extStatus < 0 || extStatus > 9999) throw profileError('QQ_PROFILE_STATUS_INVALID')
+      if (!Number.isSafeInteger(batteryStatus) || batteryStatus < 0 || batteryStatus > 100) throw profileError('QQ_PROFILE_STATUS_INVALID')
+      return writeWithLedger(sessionId, 'set_online_status', {
+        status, ext_status: extStatus, battery_status: batteryStatus,
+      }, actionId, profile => profile.status === status && profile.extStatus === extStatus)
+    },
+
+    async setAvatar({ sessionId, path: relativePath, actionId }) {
+      if (typeof sendRoot !== 'string' || !path.isAbsolute(sendRoot)) {
+        throw profileError('QQ_PROFILE_AVATAR_ROOT_INVALID')
+      }
+      const scene = await check(sessionId, 'set_qq_avatar', true)
+      if (!ledger || typeof ledger.run !== 'function') throw profileError('QQ_PROFILE_LEDGER_REQUIRED')
+      if (typeof actionId !== 'string' || !/^[\w-]{1,100}$/.test(actionId)) throw profileError('QQ_PROFILE_ACTION_ID_INVALID')
+
+      let snapshot
+      try {
+        snapshot = await snapshotControlledImage({ sendRoot, relativePath, tempRoot })
+      } catch {
+        throw profileError('QQ_PROFILE_AVATAR_INVALID')
+      }
+      const fingerprint = profileFingerprint(scene, 'set_qq_avatar', {
+        sha256: snapshot.sha256,
+        mediaType: snapshot.mediaType,
+      })
+      try {
+        return await ledger.run({
+          actionId,
+          fingerprint,
+          action: 'set_qq_avatar',
+          sessionId,
+          sceneKey: `${scene.botId}:${scene.kind}:${scene.peerId}`,
+          execute: async () => {
+            await call('set_qq_avatar', { file: snapshot.path }, true)
+            try {
+              await check(sessionId, 'set_qq_avatar', true)
+            } catch {
+              // The platform accepted the write; a later revocation is unknown.
+              throw profileError('QQ_PROFILE_UNKNOWN')
+            }
+            return { status: 'confirmed', mediaType: snapshot.mediaType, bytes: snapshot.bytes }
+          },
+        })
+      } finally {
+        await snapshot.cleanup()
+      }
+    },
+  })
+}

package/src/admin-http.js

@@ -0,0 +1,361 @@
+/**
+ * Native management HTTP surface for per-Scene QQ permissions.
+ *
+ * Every request must be same-origin, pass the DSH Connection owner admission,
+ * and POST requests must carry the `x-amadeus-qq: 1` marker. Loopback alone is
+ * never authorization: the DSH `connection.admit(req)` result is the only
+ * source of the owner principal. Model tools cannot reach this surface.
+ */
+
+import { sceneIdentity } from './storage.js'
+import { BEHAVIOR_PRESETS, CAPABILITY_CATALOG, MODE_IDS, validateScenePermissions } from './permissions.js'
+import { ownerWorkspaceStatus, providerStatus } from './owner-workspace.js'
+import { CONSOLE_CSS, CONSOLE_HTML, CONSOLE_JS } from './web-console.js'
+
+export const ADMIN_PREFIX = '/api/amadeus-qq'
+const MAX_BODY_BYTES = 64 * 1024
+
+class RequestError extends Error {
+  constructor(status, message) {
+    super(message)
+    this.status = status
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} req - Node request.
+ * @returns {boolean} whether Host/Origin state permits a same-origin request.
+ */
+export function sameOrigin(req) {
+  const host = String(req?.headers?.host ?? '')
+  if (!host) return false
+  if (req?.headers?.['sec-fetch-site'] === 'cross-site') return false
+  const origin = req?.headers?.origin
+  if (origin === undefined) return true
+  try {
+    const parsed = new URL(String(origin))
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+    return parsed.host === host
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {number} status - HTTP status.
+ * @param {Record<string, unknown>} payload - JSON body.
+ */
+function send(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'content-security-policy': "default-src 'none'",
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+function sendConsoleAsset(res, contentType, body) {
+  res.writeHead(200, {
+    'content-type': contentType,
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'referrer-policy': 'no-referrer',
+    'content-security-policy': [
+      "default-src 'none'",
+      "script-src 'self'",
+      "style-src 'self'",
+      "connect-src 'self'",
+      "img-src 'none'",
+      "object-src 'none'",
+      "base-uri 'none'",
+      "form-action 'none'",
+      "frame-ancestors 'none'",
+    ].join('; '),
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+/**
+ * Fixed, non-reflective management failure. The client uses `code` to decide
+ * whether the page must become read-only, so codes are part of the contract.
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {string} code fixed machine code.
+ * @param {string} message fixed human message; never exception/scene content.
+ */
+function fail(res, status, code, message) {
+  return send(res, status, { ok: false, code, error: message })
+}
+
+/**
+ * @param {Record<string, unknown>} connection - DSH Connection service.
+ * @param {Record<string, unknown>} req - incoming request.
+ * @returns {{ok: true}|{ok: false, status: number, message: string}} decision.
+ */
+export function authorizeRequest(connection, req) {
+  if (!connection || typeof connection.admit !== 'function') {
+    return { ok: false, status: 503, code: 'QQ_MANAGEMENT_UNAVAILABLE', message: 'native QQ management requires the DSH Connection service' }
+  }
+  let admission
+  try {
+    admission = connection.admit(req)
+  } catch {
+    return { ok: false, status: 403, code: 'QQ_AUTH_REQUIRED', message: 'request authentication failed' }
+  }
+  if (!admission || admission.rejection !== undefined) {
+    const rejection = Number(admission?.rejection)
+    const status = Number.isInteger(rejection) && rejection >= 400 && rejection <= 599 ? rejection : 403
+    return { ok: false, status, code: 'QQ_AUTH_REQUIRED', message: 'DSH authentication is required' }
+  }
+  if (admission?.peer?.principal?.kind !== 'owner') {
+    return { ok: false, status: 403, code: 'QQ_AUTH_REQUIRED', message: 'only the authenticated owner may manage QQ Scenes' }
+  }
+  return { ok: true }
+}
+
+/** @param {import('node:http').IncomingMessage} req - request. @returns {Promise<Record<string, unknown>>} parsed JSON object. */
+async function readBody(req) {
+  const contentType = String(req?.headers?.['content-type'] ?? '').toLowerCase()
+  if (!contentType.startsWith('application/json')) throw new RequestError(400, 'POST requests require application/json')
+  let size = 0
+  const chunks = []
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_BODY_BYTES) throw new RequestError(413, 'request body is too large')
+    chunks.push(chunk)
+  }
+  if (size === 0) throw new RequestError(400, 'request body is required')
+  let parsed
+  try {
+    parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw new RequestError(400, 'request body must be valid JSON')
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new RequestError(400, 'request body must be a JSON object')
+  }
+  return parsed
+}
+
+/** @param {unknown} object @param {string[]} keys @param {string} label */
+function exactKeys(object, keys, label) {
+  if (object === null || typeof object !== 'object' || Array.isArray(object)) {
+    throw new RequestError(400, `${label} must be an object`)
+  }
+  const actual = Object.keys(object).sort()
+  const expected = [...keys].sort()
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new RequestError(400, `${label} has unexpected or missing fields`)
+  }
+}
+
+/** @param {Record<string, unknown>} body */
+function parsePermissionRequest(body) {
+  exactKeys(body, ['scene', 'access', 'expectedRevision'], 'request')
+  exactKeys(body.scene, ['botId', 'kind', 'peerId'], 'scene')
+  if (body.access === null || typeof body.access !== 'object' || Array.isArray(body.access) ||
+    Object.keys(body.access).some(key => !['mode', 'overrides', 'behavior'].includes(key))) {
+    throw new RequestError(400, 'access has unexpected fields')
+  }
+  let scene
+  try {
+    scene = sceneIdentity(body.scene)
+  } catch {
+    throw new RequestError(400, 'scene is not a valid QQ Scene identity')
+  }
+  let access
+  try {
+    access = validateScenePermissions(body.access, { allowRevision: false })
+  } catch {
+    throw new RequestError(400, 'access is not a valid Scene permission request')
+  }
+  if (!Number.isSafeInteger(body.expectedRevision) || body.expectedRevision < 0) {
+    throw new RequestError(400, 'expectedRevision must be a non-negative integer')
+  }
+  return { scene, access, expectedRevision: body.expectedRevision }
+}
+
+/** @param {Record<string, unknown>} body */
+function parseResolutionRequest(body) {
+  exactKeys(body, ['scene', 'actionId', 'outcome'], 'request')
+  exactKeys(body.scene, ['botId', 'kind', 'peerId'], 'scene')
+  let scene
+  try {
+    scene = sceneIdentity(body.scene)
+  } catch {
+    throw new RequestError(400, 'scene is not a valid QQ Scene identity')
+  }
+  if (typeof body.actionId !== 'string' || !/^[\w-]{1,100}$/.test(body.actionId)) {
+    throw new RequestError(400, 'actionId is invalid')
+  }
+  if (body.outcome !== 'failed') throw new RequestError(400, 'outcome must be failed')
+  return { scene, actionId: body.actionId, outcome: body.outcome }
+}
+
+/** @param {import('node:http').ServerResponse} res @param {unknown} error */
+function sendFailure(res, error) {
+  if (error?.code === 'QQ_PERMISSION_CONFLICT') {
+    return send(res, 409, {
+      ok: false,
+      code: 'QQ_PERMISSION_CONFLICT',
+      error: 'Scene permissions changed; reload before retrying',
+      currentRevision: error.currentRevision,
+    })
+  }
+  if (error?.code === 'QQ_OWNER_AGENT_FORBIDDEN') {
+    return fail(res, 403, 'QQ_OWNER_AGENT_FORBIDDEN', 'owner-agent is limited to a configured owner private Scene')
+  }
+  if (error?.code === 'QQ_DELIVERY_IN_FLIGHT') {
+    return fail(res, 409, 'QQ_DELIVERY_IN_FLIGHT', 'an in-flight send cannot be reconciled as failed')
+  }
+  if (error?.code === 'QQ_DELIVERY_NOT_UNKNOWN') {
+    return fail(res, 409, 'QQ_DELIVERY_NOT_UNKNOWN', 'only a settled unknown delivery can be reconciled as failed')
+  }
+  if (error?.code === 'QQ_DELIVERY_NOT_FOUND') {
+    return fail(res, 404, 'QQ_DELIVERY_NOT_FOUND', 'unknown delivery not found')
+  }
+  if (error?.code === 'QQ_SCENE_UNAUTHORIZED') {
+    return fail(res, 403, 'QQ_SCENE_UNAUTHORIZED', 'Scene is outside the configured allowlist')
+  }
+  if (error?.message === 'QQ_SETUP_CONFLICT') return fail(res, 409, 'QQ_SETUP_CONFLICT', 'QQ settings changed; reload before retrying')
+  if (error?.message === 'QQ_SETUP_UNAVAILABLE' || error?.message === 'QQ_WORKSPACE_UNAVAILABLE') {
+    return fail(res, 503, 'QQ_SETUP_UNAVAILABLE', 'DSH settings or Workspace service is unavailable')
+  }
+  if (error?.message?.startsWith('QQ_HANDOFF_BUSY')) {
+    return fail(res, 503, 'QQ_HANDOFF_BUSY', 'QQ is paused, but an earlier platform action has not settled; retry after checking diagnostics')
+  }
+  if (error instanceof RequestError) return fail(res, error.status, 'QQ_REQUEST_INVALID', error.message)
+  if (error instanceof TypeError) return fail(res, 400, 'QQ_REQUEST_INVALID', 'invalid Scene or permission request')
+  const message = String(error?.message ?? '')
+  if (message.startsWith('QQ_UNAUTHORIZED')) {
+    return fail(res, 403, 'QQ_SCENE_UNAUTHORIZED', 'Scene is outside the configured allowlist')
+  }
+  if (message === 'QQ_SESSION_CANCEL_UNAVAILABLE') {
+    return fail(res, 503, 'QQ_SESSION_CANCEL_UNAVAILABLE', 'the previous QQ Session could not be cancelled safely')
+  }
+  if (message === 'QQ_SESSION_CANCEL_FAILED') {
+    return fail(res, 503, 'QQ_SESSION_CANCEL_FAILED', 'the previous QQ Session could not be cancelled safely')
+  }
+  return fail(res, 500, 'QQ_MANAGEMENT_FAILED', 'QQ management request failed')
+}
+
+/**
+ * Create the native management handler.
+ * @param {import('./core.js').QQCore} core - QQ decision core.
+ * @param {Record<string, unknown>|undefined} connection - DSH Connection service.
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>} handler.
+ */
+export function createAdminHandler(core, connection, setup = null) {
+  if (core && (typeof core.listScenePermissions !== 'function' || typeof core.setScenePermissions !== 'function')) {
+    throw new TypeError('createAdminHandler requires a QQCore')
+  }
+  return async function adminHandler(req, res) {
+    const url = new URL(String(req?.url ?? '/'), 'http://localhost')
+    if (!url.pathname.startsWith(ADMIN_PREFIX)) {
+      return fail(res, 404, 'QQ_ENDPOINT_UNKNOWN', 'not found')
+    }
+    if (!sameOrigin(req)) return fail(res, 403, 'QQ_AUTH_REQUIRED', 'same-origin request required')
+    if (req.method === 'POST' && req.headers?.['x-amadeus-qq'] !== '1') {
+      return fail(res, 403, 'QQ_AUTH_REQUIRED', 'missing QQ management request marker')
+    }
+    const auth = authorizeRequest(connection, req)
+    if (!auth.ok) return send(res, auth.status, { ok: false, code: auth.code, error: auth.message })
+
+    const path = url.pathname.slice(ADMIN_PREFIX.length) || '/'
+    if (req.method === 'GET' && path === '/setup') {
+      if (!setup) return fail(res, 503, 'QQ_SETUP_UNAVAILABLE', 'DSH settings service is unavailable')
+      try { return send(res, 200, { ok: true, data: setup.status() }) }
+      catch (error) { return sendFailure(res, error) }
+    }
+    if (req.method === 'POST' && ['/setup', '/handoff', '/scenes/allowlist', '/scenes/pause', '/account'].includes(path)) {
+      if (!setup) return fail(res, 503, 'QQ_SETUP_UNAVAILABLE', 'DSH settings service is unavailable')
+      let body
+      try { body = await readBody(req) } catch (error) { return sendFailure(res, error) }
+      try {
+        const data = path === '/setup' ? await setup.save(body, () => core?.pauseForHandoff?.())
+          : path === '/handoff' ? await setup.setConnection(body, () => core?.pauseForHandoff?.())
+          : path === '/scenes/allowlist' ? await setup.setScene(body)
+          : path === '/scenes/pause' ? await setup.pauseScene(body) : await setup.saveAccount(body)
+        return send(res, 200, { ok: true, data })
+      } catch (error) { return sendFailure(res, error) }
+    }
+    if (req.method === 'GET') {
+      if (path === '/console') {
+        return sendConsoleAsset(res, 'text/html; charset=utf-8', CONSOLE_HTML)
+      }
+      if (path === '/console.js') {
+        return sendConsoleAsset(res, 'text/javascript; charset=utf-8', CONSOLE_JS)
+      }
+      if (path === '/console.css') {
+        return sendConsoleAsset(res, 'text/css; charset=utf-8', CONSOLE_CSS)
+      }
+      if (path !== '/scenes') return fail(res, 404, 'QQ_ENDPOINT_UNKNOWN', 'unknown QQ management endpoint')
+      if (!core) return send(res, 200, { ok: true, data: { scenes: [], health: { enabled: false, transport: 'disabled' }, modes: [...MODE_IDS], behaviorPresets: BEHAVIOR_PRESETS, catalog: CAPABILITY_CATALOG, ownerWorkspace: ownerWorkspaceStatus(), providers: providerStatus() } })
+      try {
+        return send(res, 200, {
+          ok: true,
+          data: {
+            scenes: core.listScenePermissions(),
+            health: core.health(),
+            modes: [...MODE_IDS],
+            behaviorPresets: BEHAVIOR_PRESETS,
+            catalog: CAPABILITY_CATALOG,
+            ownerWorkspace: ownerWorkspaceStatus(),
+            providers: providerStatus(),
+          },
+        })
+      } catch {
+        return fail(res, 500, 'QQ_MANAGEMENT_FAILED', 'QQ management request failed')
+      }
+    }
+    if (req.method !== 'POST') return fail(res, 405, 'QQ_METHOD_NOT_ALLOWED', 'method not allowed')
+    if (path !== '/scenes/permissions' && path !== '/deliveries/resolve') {
+      return fail(res, 404, 'QQ_ENDPOINT_UNKNOWN', 'unknown QQ management endpoint')
+    }
+    if (!core) return fail(res, 503, 'QQ_MANAGEMENT_UNAVAILABLE', 'QQ connector is not enabled')
+    let body
+    try {
+      body = await readBody(req)
+    } catch (error) {
+      return sendFailure(res, error)
+    }
+    if (path === '/deliveries/resolve') {
+      let resolution
+      try {
+        resolution = parseResolutionRequest(body)
+      } catch (error) {
+        return sendFailure(res, error)
+      }
+      try {
+        if (typeof core.resolveDelivery !== 'function') {
+          return fail(res, 503, 'QQ_MANAGEMENT_UNAVAILABLE', 'QQ delivery reconciliation is unavailable')
+        }
+        await core.resolveDelivery(resolution.scene, resolution.actionId, resolution.outcome)
+        return send(res, 200, { ok: true, data: { status: 'failed' } })
+      } catch (error) {
+        return sendFailure(res, error)
+      }
+    }
+    let parsed
+    try {
+      parsed = parsePermissionRequest(body)
+    } catch (error) {
+      return sendFailure(res, error)
+    }
+    try {
+      const permissions = await core.setScenePermissions(parsed.scene, parsed.access, {
+        expectedRevision: parsed.expectedRevision,
+      })
+      return send(res, 200, { ok: true, data: { permissions } })
+    } catch (error) {
+      return sendFailure(res, error)
+    }
+  }
+}