codeh007 · codeh007 · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -57,3 +57,17 @@ jobs:
 
       - name: Lint mtmharness package metadata
         run: pnpm dlx publint run "${{ steps.pack.outputs.tarball }}" --strict
+
+      - name: Pack mtm-admin bundle
+        id: pack-admin
+        run: |
+          set -euo pipefail
+          pack_dir="$RUNNER_TEMP/mtm-admin"
+          mkdir -p "$pack_dir"
+          pnpm --filter mtm-admin pack --pack-destination "$pack_dir"
+          tarball="$(find "$pack_dir" -maxdepth 1 -type f -name 'mtm-admin-*.tgz' -print -quit)"
+          test -n "$tarball"
+          printf 'tarball=%s\n' "$tarball" >> "$GITHUB_OUTPUT"
+
+      - name: Lint mtm-admin package metadata
+        run: pnpm dlx publint run "${{ steps.pack-admin.outputs.tarball }}" --strict
diff --git a/.github/workflows/release-mtm-admin.yml b/.github/workflows/release-mtm-admin.yml
@@ -0,0 +1,135 @@
+name: release-mtm-admin
+run-name: Release mtm-admin ${{ github.ref_name }}
+
+on:
+  push:
+    tags:
+      - 'mtm-admin-v[0-9]*.[0-9]*.[0-9]*'
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: mtm-admin-npm-publish
+  cancel-in-progress: false
+
+env:
+  PACKAGE_NAME: mtm-admin
+  PACKAGE_DIR: packages/mtm-admin
+  TAG_PREFIX: mtm-admin-v
+
+jobs:
+  publish:
+    name: Pack, publish, and read back mtm-admin
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout tagged main commit
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.7.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Verify pnpm version
+        run: test "$(pnpm --version)" = 11.7.0
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate tag and main ancestry
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          package_version="$(node -p "require('./${PACKAGE_DIR}/package.json').version")"
+          test "$RELEASE_TAG" = "${TAG_PREFIX}${package_version}"
+          git fetch --no-tags origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+          printf 'PACKAGE_VERSION=%s\n' "$package_version" >> "$GITHUB_ENV"
+
+      - name: Check browser extension and manifest pin
+        run: |
+          set -euo pipefail
+          pnpm --filter mtm-admin run check
+          package_version="$(node -p "require('./${PACKAGE_DIR}/package.json').version")"
+          manifest_version="$(sed -n '/id: "mtm-admin"/{n;s/.*version: "\([^\"]*\)".*/\1/p;}' packages/mtmharness/src/features/secondary/manifest.ts)"
+          expected_integrity="$(sed -n '/id: "mtm-admin"/{n;n;n;s/.*clientIntegrity: "\([^\"]*\)".*/\1/p;}' packages/mtmharness/src/features/secondary/manifest.ts)"
+          test "$manifest_version" = "$package_version"
+          local_integrity="sha256-$(openssl dgst -sha256 -binary packages/mtm-admin/lib/client.js | base64 -w0)"
+          test "$local_integrity" = "$expected_integrity"
+          printf 'EXPECTED_INTEGRITY=%s\n' "$expected_integrity" >> "$GITHUB_ENV"
+
+      - name: Pack release tarball
+        id: pack
+        run: |
+          set -euo pipefail
+          pack_dir="$RUNNER_TEMP/mtm-admin"
+          mkdir -p "$pack_dir"
+          pnpm --filter mtm-admin pack --pack-destination "$pack_dir"
+          tarball="$(find "$pack_dir" -maxdepth 1 -type f -name "${PACKAGE_NAME}-*.tgz" -print -quit)"
+          test -n "$tarball"
+          local_integrity="sha512-$(openssl dgst -sha512 -binary "$tarball" | base64 -w0)"
+          printf 'tarball=%s\n' "$tarball" >> "$GITHUB_OUTPUT"
+          printf 'LOCAL_INTEGRITY=%s\n' "$local_integrity" >> "$GITHUB_ENV"
+
+      - name: Lint package metadata
+        run: pnpm dlx publint run "${{ steps.pack.outputs.tarball }}" --strict
+
+      - name: Preflight registry and token
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          test -n "${NODE_AUTH_TOKEN:-}"
+          npm whoami --registry=https://registry.npmjs.org >/dev/null
+          status="$(curl --silent --show-error --location --output /dev/null --write-out '%{http_code}' "https://registry.npmjs.org/${PACKAGE_NAME}/${PACKAGE_VERSION}")"
+          test "$status" = 404
+
+      - name: Publish with provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish "${{ steps.pack.outputs.tarball }}" --access public --provenance --ignore-scripts
+
+      - name: Read back npm and CDN artifacts
+        run: |
+          set -euo pipefail
+          remote="$RUNNER_TEMP/mtm-admin-client.js"
+          for attempt in $(seq 1 12); do
+            published_integrity="$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" dist.integrity --json 2>/dev/null | jq -r . || true)"
+            published_version="$(npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version --json 2>/dev/null | jq -r . || true)"
+            curl --fail --silent --show-error --location --output "$remote" "https://unpkg.com/${PACKAGE_NAME}@${PACKAGE_VERSION}/lib/client.js" || true
+            remote_integrity=""
+            test -f "$remote" && remote_integrity="sha256-$(openssl dgst -sha256 -binary "$remote" | base64 -w0)"
+            if test "$published_integrity" = "$LOCAL_INTEGRITY" && test "$published_version" = "$PACKAGE_VERSION" && test "$remote_integrity" = "$EXPECTED_INTEGRITY" && cmp packages/mtm-admin/lib/client.js "$remote"; then
+              break
+            fi
+            if test "$attempt" -eq 12; then
+              echo "npm/CDN artifact read-back did not converge after ${attempt} attempts" >&2
+              exit 1
+            fi
+            sleep 5
+          done
+          {
+            echo '### npm release evidence'
+            echo
+            echo "- package: ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+            echo "- tag: ${GITHUB_REF_NAME}"
+            echo "- integrity: ${published_integrity}"
+            echo '- provenance: requested with npm publish --provenance'
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release-mtmharness.yml b/.github/workflows/release-mtmharness.yml
@@ -69,6 +69,7 @@ jobs:
           pnpm --filter mtmharness run check
           pnpm --filter mtmcanvas run check
           pnpm --filter mtm-connect run check
+          pnpm --filter mtm-admin run check
           # The pinned secondary artifacts must already be published before mtmharness.
           canvas_version="$(node -p "require('./packages/mtmcanvas/package.json').version")"
           canvas_integrity="$(sed -n '/id: "mtmcanvas"/{n;n;n;s/.*clientIntegrity: "\([^\"]*\)".*/\1/p;}' packages/mtmharness/src/features/secondary/manifest.ts)"
@@ -92,6 +93,16 @@ jobs:
           remote_integrity="sha256-$(openssl dgst -sha256 -binary "$remote" | base64 -w0)"
           test "$remote_integrity" = "$connect_integrity"
           cmp "packages/mtm-connect/lib/client.js" "$remote"
+          admin_version="$(node -p "require('./packages/mtm-admin/package.json').version")"
+          admin_integrity="$(sed -n '/id: "mtm-admin"/{n;n;n;s/.*clientIntegrity: "\([^\"]*\)".*/\1/p;}' packages/mtmharness/src/features/secondary/manifest.ts)"
+          local_integrity="sha256-$(openssl dgst -sha256 -binary packages/mtm-admin/lib/client.js | base64 -w0)"
+          test "$admin_integrity" = "$local_integrity"
+          test "$(npm view "mtm-admin@${admin_version}" version --json | jq -r .)" = "$admin_version"
+          remote="$RUNNER_TEMP/mtm-admin-client.js"
+          curl --fail --silent --show-error --output "$remote" "https://unpkg.com/mtm-admin@${admin_version}/lib/client.js"
+          remote_integrity="sha256-$(openssl dgst -sha256 -binary "$remote" | base64 -w0)"
+          test "$remote_integrity" = "$admin_integrity"
+          cmp "packages/mtm-admin/lib/client.js" "$remote"
 
       - name: Pack release tarball
         id: pack

diff --git a/package.json b/package.json
@@ -5,9 +5,9 @@
   "packageManager": "pnpm@11.7.0",
   "engines": { "node": ">=22.19.0" },
   "scripts": {
-    "build": "pnpm --filter mtmharness run build",
+    "build": "pnpm --filter mtmharness run build && pnpm --filter mtm-admin run build",
     "demo": "pnpm --filter mtmharness run dev",
-    "check": "pnpm --filter mtmharness run check && pnpm --filter mtmcanvas run check && pnpm --filter mtm-connect run check"
+    "check": "pnpm --filter mtmharness run check && pnpm --filter mtmcanvas run check && pnpm --filter mtm-connect run check && pnpm --filter mtm-admin run check"
   },
   "devDependencies": { "typescript": "6.0.3" }
 }
diff --git a/packages/mtm-admin/LICENSE b/packages/mtm-admin/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codeh007
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/mtm-admin/README.md b/packages/mtm-admin/README.md
@@ -0,0 +1,49 @@
+# mtm-admin
+
+mtm-admin is the independent browser control-plane client for gomtm. It is public source and is not a standard DSH profile plugin. The package publishes a standalone static app, a programmatic embed, and a token-free mtmharness secondary launcher.
+
+## Static app
+
+Serve dist/standalone as the app root and provide a sibling config.js before the module script runs:
+
+    window.__MTM_ADMIN_CONFIG__ = {
+      apiOrigin: "https://gomtm.example.test",
+      oauth: {
+        issuer: "https://gomtm.example.test",
+        clientId: "mtm-admin-web-v1",
+        redirectUri: "https://admin.example.test/",
+        resource: "https://gomtm.example.test/api/system",
+        scopes: ["openid", "profile", "email", "offline_access", "gomtm:admin"]
+      }
+    };
+
+The OAuth client uses Authorization Code with PKCE S256. The exact redirect URI must be registered at the authority. Tokens stay in JavaScript memory; only the short-lived PKCE transaction uses sessionStorage. API requests send Authorization Bearer and credentials omit. No cookie session is used.
+
+## mtmharness launcher
+
+mtmharness owns the trusted secondary manifest and loads mtm-admin's lib/client.js after the user enables the feature. The launcher only opens the configured standalone app URL and never receives a token. The host must point the manifest at a deployment of the static app that has its own public OAuth configuration.
+
+The launcher uses the existing mount(context) -> cleanup contract. Its integrity pin identifies the reviewed artifact; it is not a JavaScript sandbox.
+
+## Embed
+
+The mtm-admin/embed export mounts the full React application into a caller-owned element:
+
+    import { mount } from "mtm-admin/embed";
+    const unmount = mount(document.querySelector("#admin"), {
+      apiOrigin: "https://gomtm.example.test",
+      oauth: {
+        issuer: "https://gomtm.example.test",
+        clientId: "mtm-admin-web-v1",
+        redirectUri: "https://host.example.test/admin/callback",
+        resource: "https://gomtm.example.test/api/system",
+        scopes: ["openid", "gomtm:admin"]
+      }
+    });
+
+Use the standalone app or launcher for the high-privilege default. Inline embed is an explicit opt-in because it executes in the caller page.
+
+## Development
+
+    pnpm --filter mtmharness run build
+    pnpm --filter mtm-admin run check
diff --git a/packages/mtm-admin/index.html b/packages/mtm-admin/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="mtm-admin-frame-ancestors" content="none" />
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; connect-src 'self' https:; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self';" />
+    <link rel="icon" href="data:," />
+    <title>MTM Administrator</title>
+    <script src="%BASE_URL%config.js"></script>
+  </head>
+  <body>
+    <main id="root"></main>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/packages/mtm-admin/package.json b/packages/mtm-admin/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "mtm-admin",
+  "version": "0.1.0",
+  "description": "Independent OAuth control-plane client and mtmharness launcher for gomtm.",
+  "type": "module",
+  "engines": { "node": ">=22.19.0", "pnpm": ">=11.7.0" },
+  "main": "./lib/client.js",
+  "types": "./lib/types/launcher.d.ts",
+  "exports": {
+    ".": { "types": "./lib/types/launcher.d.ts", "import": "./lib/client.js", "default": "./lib/client.js" },
+    "./client": { "types": "./lib/types/launcher.d.ts", "import": "./lib/client.js", "default": "./lib/client.js" },
+    "./embed": { "types": "./lib/types/embed.d.ts", "import": "./dist/embed/mtm-admin.js", "default": "./dist/embed/mtm-admin.js" },
+    "./app": "./dist/standalone/index.html",
+    "./package.json": "./package.json"
+  },
+  "mtmharness": {
+    "secondary": { "id": "mtm-admin", "apiVersion": 1, "client": "./lib/client.js" }
+  },
+  "files": [
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "dist/standalone",
+    "dist/embed",
+    "README.md",
+    "package.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "pretypecheck": "pnpm --filter mtmharness run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build",
+    "prepack": "pnpm run build"
+  },
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/codeh007/mtmdsh.git", "directory": "packages/mtm-admin" },
+  "devDependencies": {
+    "@base-ui/react": "1.7.0",
+    "@tailwindcss/vite": "4.3.3",
+    "@types/node": "22.20.1",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "@testing-library/react": "16.3.2",
+    "@vitejs/plugin-react": "6.0.5",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "esbuild": "0.28.2",
+    "jsdom": "30.0.1",
+    "lucide-react": "1.21.0",
+    "mtmharness": "workspace:*",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tailwind-merge": "3.6.0",
+    "tailwindcss": "4.3.0",
+    "tw-animate-css": "1.4.0",
+    "typescript": "6.0.3",
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
+  }
+}
diff --git a/packages/mtm-admin/public/config.js b/packages/mtm-admin/public/config.js
@@ -0,0 +1 @@
+// Deployment-owned public configuration is injected here before the app module runs.
diff --git a/packages/mtm-admin/scripts/build.mjs b/packages/mtm-admin/scripts/build.mjs
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const libRoot = resolve(packageRoot, "lib");
+const distRoot = resolve(packageRoot, "dist");
+const tsc = resolve(packageRoot, "node_modules/.bin/tsc");
+const vite = resolve(packageRoot, "node_modules/.bin/vite");
+
+rmSync(libRoot, { recursive: true, force: true });
+rmSync(distRoot, { recursive: true, force: true });
+mkdirSync(libRoot, { recursive: true });
+if (!existsSync(tsc) || !existsSync(vite)) throw new Error("mtm-admin build: local TypeScript and Vite executables are required");
+
+execFileSync(tsc, ["--project", resolve(packageRoot, "tsconfig.json")], { cwd: packageRoot, stdio: "inherit" });
+await build({
+  entryPoints: [resolve(packageRoot, "src/launcher.ts")],
+  outfile: resolve(libRoot, "client.js"),
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2020",
+  legalComments: "none",
+  logLevel: "info",
+});
+execFileSync(vite, ["build", "--config", resolve(packageRoot, "vite.config.ts")], { cwd: packageRoot, stdio: "inherit" });
+execFileSync(vite, ["build", "--config", resolve(packageRoot, "vite.embed.config.ts")], { cwd: packageRoot, stdio: "inherit" });
+
+console.log("built mtm-admin standalone, embed, and launcher artifacts");
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		// Deployment-owned public configuration is injected here before the app module runs.