mango-cms 0.3.33 → 0.3.35

package/lib/vibe-orchestrator/src/config.js

@@ -0,0 +1,227 @@
+// config.js
+//
+// Centralized env reading + validation for the orchestrator. The OAuth token is
+// never read from git — it lives in /root/.vibe-orchestrator.env on the droplet
+// (chmod 600) and is sourced into the process env before launch (see README).
+
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+function envInt(name, fallback) {
+  const v = process.env[name]
+  if (v == null || v === '') return fallback
+  const n = Number.parseInt(v, 10)
+  return Number.isFinite(n) ? n : fallback
+}
+
+const config = {
+  // HTTP/SSE listen port for the orchestrator service.
+  port: envInt('VIBE_ORCH_PORT', 7130),
+
+  // Root under which each <site> is a clone, e.g. /root/Staging/<site>.
+  stagingRoot: process.env.VIBE_STAGING_ROOT || '/root/Staging',
+
+  // Whitelist of site slugs the orchestrator is allowed to operate on. Empty =>
+  // any directory directly under stagingRoot is permitted (still path-guarded).
+  allowedSites: (process.env.VIBE_ALLOWED_SITES || 'generations-vibe')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // claude CLI binary (v2.1.157 installed at /usr/local/bin/claude on droplet).
+  claudeBin: process.env.VIBE_CLAUDE_BIN || 'claude',
+
+  // Per-session cumulative token cap. 0 = unlimited. Raised from 200k → 2M
+  // (HAP-1096): a real vibe session reads files + viewport screenshots (images are
+  // token-heavy) and 200k was tripping mid-demo. Cost is still tracked + billed per
+  // turn, so this is a runaway-safety rail, not a budget — tune via VIBE_TOKEN_CAP.
+  tokenCap: envInt('VIBE_TOKEN_CAP', 2_000_000),
+
+  // Headless permission mode. Deliberately NOT bypassPermissions: this droplet is
+  // shared (it hosts ~40 other production sites) and the orchestrator runs as root,
+  // so blanket-allowing Bash would let an errant run `rm -rf` a sibling tenant — a
+  // blast radius the HAP-1124 path guard does NOT cover (it only matches Edit/Write,
+  // not Bash). acceptEdits keeps that destructive/network Bash gated while still
+  // auto-accepting file edits on the throwaway clone. The HAP-1096 web-fetch +
+  // screenshot-read failures are fixed surgically instead via `allowedTools` +
+  // `toolExtraDirs` below — read-only capabilities with no shared-droplet risk.
+  permissionMode: process.env.VIBE_PERMISSION_MODE || 'acceptEdits',
+
+  // Tools pre-approved for headless runs (no interactive approver exists, so
+  // otherwise-gated tools are auto-DENIED). WebFetch/WebSearch are read-only network
+  // reads with no filesystem/destructive risk — enabling them lets the owner say
+  // "use our real logo + brand blue from generations.org" and have it work (HAP-1096,
+  // where WebFetch showed "isn't permitted here"). Space/comma separated override.
+  allowedTools: (process.env.VIBE_ALLOWED_TOOLS || 'WebFetch WebSearch')
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // Extra directories the run's tools may access (--add-dir). The viewport
+  // screenshot and any pasted/uploaded attachments are persisted OUTSIDE the cwd
+  // (os.tmpdir()/vibe-orchestrator, so they never land in the editable clone); under
+  // acceptEdits the agent otherwise can't Read them — that is the HAP-1096 "screenshot
+  // file gated behind approval" failure. Allowing this one temp dir restores the read.
+  toolExtraDirs: (
+    process.env.VIBE_TOOL_EXTRA_DIRS
+    || path.join(os.tmpdir(), 'vibe-orchestrator')
+  )
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // Optional model override (e.g. claude-opus-4-8). Empty => CLI default.
+  model: process.env.VIBE_MODEL || '',
+
+  // The OAuth token. An EXPLICIT token is optional: when empty, live runs use
+  // the claude CLI's own auto-refreshing login credentials instead (the Phase-1
+  // decision — "Claude Code CLI not API key"). Never required for the server to
+  // boot — scaffold/stream-parse/session work runs token-free.
+  oauthToken: process.env.CLAUDE_CODE_OAUTH_TOKEN || '',
+
+  // Path to the claude CLI's auto-refreshing login credentials. When present,
+  // live runs work without an explicit oauthToken. Override only in tests.
+  claudeCredentialsPath:
+    process.env.VIBE_CLAUDE_CREDENTIALS
+    || path.join(os.homedir(), '.claude', '.credentials.json'),
+
+  // Wall-clock ceiling for a single claude invocation (ms). 0 = no timeout.
+  runTimeoutMs: envInt('VIBE_RUN_TIMEOUT_MS', 10 * 60 * 1000),
+
+  // ---- Publish (staging → prod via the existing pipeline; HAP-1103) ----
+
+  // Master switch for the publish endpoints. The actual `git push` is also
+  // gated by an explicit per-call confirm; this is the operator-level kill switch.
+  publishEnabled: String(process.env.VIBE_PUBLISH_ENABLED ?? 'true').toLowerCase() !== 'false',
+
+  // Remote the publish push targets (push to its tracked branch → ssh-deploy).
+  publishRemote: process.env.VIBE_PUBLISH_REMOTE || 'origin',
+
+  // Deploy branch each workspace branch merges INTO on publish. ssh-deploy only
+  // triggers on a push to this branch (`.github/workflows/ssh-deploy.yml` →
+  // update.sh on prod), so a per-branch workspace must merge here to reach prod.
+  // When a workspace is already on this branch, publish pushes it directly.
+  publishBranch: process.env.VIBE_PUBLISH_BRANCH || 'main',
+
+  // Env-specific file that must NEVER be pushed. The staging overlay materializes
+  // the staging block into it; publish restores it (`git checkout`) before commit.
+  settingsPath: process.env.VIBE_SETTINGS_PATH || 'mango/config/settings.json',
+
+  // ---- Self-protection: path guard + rollback (HAP-1124) ----
+
+  // Server-side denylist enforcement. When true, every live run is launched with
+  // a PreToolUse hook (scripts/path-guard-hook.mjs) that blocks edits to the Vibe
+  // system itself (drawer, orchestrator, staging spine, settings, deploy/CI). This
+  // is enforced regardless of the prompt. Disable only for tests/debugging.
+  pathGuardEnabled: String(process.env.VIBE_PATH_GUARD ?? 'true').toLowerCase() !== 'false',
+
+  // Absolute path to the PreToolUse hook script. Lives in the orchestrator tree
+  // (itself protected), never inside the editable site clone.
+  pathGuardHook:
+    process.env.VIBE_PATH_GUARD_HOOK
+    || path.resolve(__dirname, '..', 'scripts', 'path-guard-hook.mjs'),
+
+  // Auto-commit every applied vibe edit to the staging clone's git history and
+  // keep a known-good baseline tag, so there is always a way back (revert last /
+  // reset to baseline). Disable only for tests that drive a fake runner.
+  autoCommitEnabled: String(process.env.VIBE_AUTO_COMMIT ?? 'true').toLowerCase() !== 'false',
+
+  // Annotated tag marking the known-good baseline a "reset to baseline" returns to.
+  baselineTag: process.env.VIBE_BASELINE_TAG || 'vibe-baseline',
+
+  // ---- Owner auth (HAP-1109) ----
+
+  // HMAC secret shared ONLY between Mango (which mints owner tokens from an
+  // authenticated admin session) and this orchestrator (which verifies them).
+  // Lives in /root/.vibe-orchestrator.env on the droplet (chmod 600), never in
+  // git. UNSET ⇒ the orchestrator fails CLOSED: every gated endpoint returns 503
+  // until it is configured. This is the real per-owner gate that replaces the old
+  // optional shared secret.
+  tokenSecret: process.env.VIBE_ORCH_TOKEN_SECRET || '',
+
+  // Roles that count as a site owner (any match grants access).
+  ownerRoles: (process.env.VIBE_OWNER_ROLES || 'admin')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // ---- Cost tracking (HAP-1123) ----
+
+  // Client-facing markup on the RAW API cost, as a percentage (board request on
+  // HAP-1123). 100 ⇒ a 100% markup ⇒ the client is shown/billed 2× the raw cost.
+  // The raw CLI cost stays the persisted source of truth; the markup is applied
+  // only at display + rollup time so the rate can change without rewriting history.
+  markupPct: envInt('VIBE_COST_MARKUP_PCT', 100),
+
+  // Mango ingest endpoint that mirrors each per-turn cost record into the
+  // `vibeCosts` collection (queryable in the CMS for invoicing). UNSET ⇒ the
+  // mirror is a no-op and the orchestrator's local NDJSON log is the only store
+  // (the rollup endpoint reads from it either way). Authenticated with the shared
+  // VIBE_ORCH_TOKEN_SECRET as a bearer; intended to point at localhost Mango.
+  costMirrorUrl: process.env.VIBE_COST_MIRROR_URL || '',
+
+  // ---- CORS (HAP-1121) ----
+
+  // Browser origins allowed to call the orchestrator cross-origin. The ⌘K drawer
+  // is served from the SITE origin (e.g. https://staging-vibe.generations.org)
+  // and calls the orchestrator on the -api origin, so the browser issues a CORS
+  // preflight. Without an allow-list + preflight handling every call surfaces as
+  // "Failed to fetch". Empty list ⇒ reflect any origin (dev only). Prod + staging
+  // site origins are the defaults.
+  allowedOrigins: (
+    process.env.VIBE_ALLOWED_ORIGINS
+    || 'https://staging-vibe.generations.org,https://vibe.generations.org,http://localhost:7121'
+  )
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // ---- Idle session reaping (HAP-1110) ----
+
+  // How long a session may sit idle (no prompts, no keepalive touches, no open
+  // readers) before it is reaped so the next prompt starts a fresh conversation.
+  // A running run or an open SSE reader always keeps it warm. 0 = never reap.
+  sessionIdleMs: envInt('VIBE_SESSION_IDLE_MS', 30 * 60 * 1000),
+
+  // How often the reaper sweeps. Kept well below sessionIdleMs.
+  reaperIntervalMs: envInt('VIBE_REAPER_INTERVAL_MS', 60 * 1000),
+}
+
+/** Resolve + validate a site slug to an absolute, in-root working directory. */
+function resolveSiteDir(site) {
+  if (!site || typeof site !== 'string' || !/^[a-zA-Z0-9._-]+$/.test(site)) {
+    throw new Error(`invalid site slug: ${JSON.stringify(site)}`)
+  }
+  if (config.allowedSites.length && !config.allowedSites.includes(site)) {
+    throw new Error(`site not in allowlist: ${site}`)
+  }
+  const dir = path.resolve(config.stagingRoot, site)
+  // Guard against traversal escaping the staging root.
+  if (dir !== path.join(config.stagingRoot, site)) {
+    throw new Error(`resolved path escapes staging root: ${site}`)
+  }
+  return dir
+}
+
+/** True when the claude CLI's auto-refreshing login credentials are present. */
+function hasCliCredentials() {
+  try {
+    return fs.existsSync(config.claudeCredentialsPath)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * True when a live claude run is possible: either an explicit OAuth token is
+ * configured, OR the claude CLI has its own login credentials to fall back on.
+ */
+function canRunLive() {
+  return !!config.oauthToken || hasCliCredentials()
+}
+
+export { config, resolveSiteDir, canRunLive, hasCliCredentials }

package/lib/vibe-orchestrator/src/costMirror.js

@@ -0,0 +1,64 @@
+// costMirror.js
+//
+// Best-effort mirror of a per-turn cost record into the Mango `vibeCosts`
+// collection (HAP-1123). The orchestrator's NDJSON log (costStore) is the durable
+// system of record; this mirror makes the same record queryable in the CMS so the
+// board can invoice from it. A mango outage NEVER loses data — the local log
+// already has every record and the orchestrator rollup endpoint reads from it.
+//
+// Transport: a plain POST to the Mango ingest endpoint on localhost, authenticated
+// with the shared VIBE_ORCH_TOKEN_SECRET as a bearer. Disabled (no-op) unless
+// VIBE_COST_MIRROR_URL is configured, so it is fail-safe by default.
+
+import http from 'node:http'
+import https from 'node:https'
+import { config } from './config.js'
+
+/**
+ * POST one normalized cost record to the Mango ingest endpoint. Resolves to
+ * `{ ok }`; never rejects (callers treat it as fire-and-forget). No-op when the
+ * mirror URL or shared secret is unset.
+ *
+ * @param {object} entry              normalized cost record (from costStore)
+ * @param {object} [opts]
+ * @param {string} [opts.url]         override the mirror URL (tests)
+ * @param {string} [opts.secret]      override the bearer secret (tests)
+ * @param {function} [opts.requestFn] injectable transport (tests)
+ */
+function mirrorCost(entry, opts = {}) {
+  const url = opts.url || config.costMirrorUrl
+  const secret = opts.secret || config.tokenSecret
+  if (!url || !secret || !entry) return Promise.resolve({ ok: false, skipped: true })
+
+  return new Promise((resolve) => {
+    let target
+    try { target = new URL(url) } catch { return resolve({ ok: false, error: 'bad mirror url' }) }
+    const lib = target.protocol === 'https:' ? https : http
+    const requestFn = opts.requestFn || lib.request
+    const body = JSON.stringify(entry)
+    const req = requestFn(
+      {
+        hostname: target.hostname,
+        port: target.port,
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+          authorization: `Bearer ${secret}`,
+        },
+        timeout: 5000,
+      },
+      (res) => {
+        res.resume() // drain
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode })
+      },
+    )
+    req.on('error', () => resolve({ ok: false }))
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }) })
+    req.write(body)
+    req.end()
+  })
+}
+
+export { mirrorCost }

package/lib/vibe-orchestrator/src/costStore.js

@@ -0,0 +1,209 @@
+// costStore.js
+//
+// Durable per-turn cost log for the vibe assistant (HAP-1123). Append-only NDJSON
+// so it survives orchestrator restarts and stays queryable without standing up a
+// DB inside this dependency-free service. One line per completed turn:
+//
+//   { ts, site, path, sessionId, model, costUsd, tokens:{input,output,cacheRead,
+//     total,billable}, promptSummary, ok }
+//
+// The CLI's reported `total_cost_usd` is the source of truth for `costUsd`
+// (captured in claudeRunner). When the CLI omits a cost we fall back to a
+// model→price table (estimateCostUsd) so a record is never cost-less.
+//
+// Pure of the clock: callers pass `ts`. fs is touched only on append/read so the
+// rollup math stays unit-testable against an injected path.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { config } from './config.js'
+
+/** Default NDJSON log location. Override with VIBE_COST_LOG (absolute path). */
+function defaultLogPath() {
+  return process.env.VIBE_COST_LOG || path.join(config.stagingRoot, '.vibe-costs.ndjson')
+}
+
+// Per-MTok USD prices (input / output) used ONLY when the CLI omits a cost. These
+// are coarse list prices for sanity, not billing truth — the CLI's
+// total_cost_usd is authoritative and is what we persist when present.
+const PRICE_TABLE = [
+  { match: /opus/i, inPerMTok: 15, outPerMTok: 75 },
+  { match: /sonnet/i, inPerMTok: 3, outPerMTok: 15 },
+  { match: /haiku/i, inPerMTok: 0.8, outPerMTok: 4 },
+]
+
+/**
+ * Estimate a turn's cost from tokens when the CLI didn't report one. Cache-read
+ * input is billed at the same coarse input rate here (good enough for a fallback;
+ * the CLI's real number already accounts for cache discounts when available).
+ * @returns {number|null} USD, or null when the model is unknown
+ */
+function estimateCostUsd({ model, inputTokens = 0, outputTokens = 0 } = {}) {
+  if (!model) return null
+  const row = PRICE_TABLE.find((r) => r.match.test(model))
+  if (!row) return null
+  return (inputTokens / 1e6) * row.inPerMTok + (outputTokens / 1e6) * row.outPerMTok
+}
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0
+}
+
+/**
+ * Apply the client-facing markup to a raw cost. `pct` is a percentage (100 ⇒ 2×).
+ * Returns null when the cost is absent so a missing cost never becomes $0.00.
+ * @param {number|null} cost  raw USD
+ * @param {number} pct        markup percent
+ */
+function applyMarkup(cost, pct) {
+  if (typeof cost !== 'number' || !Number.isFinite(cost)) return null
+  return cost * (1 + num(pct) / 100)
+}
+
+/**
+ * Normalize a raw record into the durable shape. Coerces token numbers and
+ * back-fills `costUsd` from the price table when absent. `ts` defaults to 0 so
+ * the module never reads the clock — real callers pass Date.now().
+ */
+function normalizeEntry(raw = {}) {
+  const t = raw.tokens || {}
+  const tokens = {
+    input: num(t.input ?? t.inputTokens),
+    output: num(t.output ?? t.outputTokens),
+    cacheRead: num(t.cacheRead ?? t.cacheReadTokens),
+    total: num(t.total ?? t.totalTokens),
+    billable: num(t.billable ?? t.billableTokens),
+  }
+  let costUsd = typeof raw.costUsd === 'number' && Number.isFinite(raw.costUsd) ? raw.costUsd : null
+  let costEstimated = false
+  if (costUsd == null) {
+    const est = estimateCostUsd({ model: raw.model, inputTokens: tokens.input, outputTokens: tokens.output })
+    if (est != null) { costUsd = est; costEstimated = true }
+  }
+  return {
+    ts: num(raw.ts),
+    site: raw.site || null,
+    path: raw.path || null,
+    sessionId: raw.sessionId || null,
+    model: raw.model || null,
+    costUsd,
+    costEstimated,
+    tokens,
+    promptSummary: raw.promptSummary || '',
+    ok: raw.ok !== false,
+  }
+}
+
+/**
+ * Append one cost record as an NDJSON line. Creates the parent dir if needed.
+ * Returns the normalized record. Throws on fs failure — callers wrap this in a
+ * best-effort try/catch so cost logging never breaks a run.
+ */
+function appendCost(raw, logPath = defaultLogPath()) {
+  const entry = normalizeEntry(raw)
+  fs.mkdirSync(path.dirname(logPath), { recursive: true })
+  fs.appendFileSync(logPath, JSON.stringify(entry) + '\n')
+  return entry
+}
+
+/** Read all records, tolerating partial/corrupt trailing lines. */
+function readAll(logPath = defaultLogPath()) {
+  let text
+  try {
+    text = fs.readFileSync(logPath, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return []
+    throw e
+  }
+  const out = []
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s) continue
+    try { out.push(JSON.parse(s)) } catch { /* skip a torn line */ }
+  }
+  return out
+}
+
+/** Read records filtered to the [from, to] ms window (inclusive). */
+function readCosts({ from, to, site } = {}, logPath = defaultLogPath()) {
+  return readAll(logPath).filter((r) => {
+    if (typeof from === 'number' && num(r.ts) < from) return false
+    if (typeof to === 'number' && num(r.ts) > to) return false
+    if (site && r.site !== site) return false
+    return true
+  })
+}
+
+/** UTC YYYY-MM-DD for a ms timestamp. */
+function dayKey(ts) {
+  return new Date(num(ts)).toISOString().slice(0, 10)
+}
+
+function emptyBucket() {
+  return { count: 0, costUsd: 0, billedUsd: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+}
+
+function addTo(bucket, r, pct) {
+  bucket.count += 1
+  bucket.costUsd += num(r.costUsd)
+  bucket.billedUsd += num(applyMarkup(num(r.costUsd), pct))
+  const t = r.tokens || {}
+  bucket.inputTokens += num(t.input)
+  bucket.outputTokens += num(t.output)
+  bucket.totalTokens += num(t.total)
+}
+
+/**
+ * Sum a date window into a rollup the board can invoice from. Groups by UTC day,
+ * by session, and by model. `costUsd` is the RAW API cost (CLI's total_cost_usd);
+ * `billedUsd` is that cost with the client-facing markup applied (HAP-1123 board
+ * request). The rollup carries both plus the `markupPct` used, so the board sees
+ * raw and client-billed side by side.
+ *
+ * @param {{from?,to?,site?,markupPct?}} [opts] markupPct defaults to config
+ * @returns {{
+ *   from, to, markupPct, count, totalCostUsd, totalBilledUsd, totalTokens,
+ *   byDay: Object, bySession: Object, byModel: Object
+ * }}
+ */
+function rollup({ from, to, site, markupPct } = {}, logPath = defaultLogPath()) {
+  const pct = num(markupPct != null ? markupPct : config.markupPct)
+  const rows = readCosts({ from, to, site }, logPath)
+  const byDay = {}
+  const bySession = {}
+  const byModel = {}
+  let totalCostUsd = 0
+  let totalTokens = 0
+  for (const r of rows) {
+    totalCostUsd += num(r.costUsd)
+    totalTokens += num(r.tokens?.total)
+    const d = dayKey(r.ts)
+    ;(byDay[d] ||= emptyBucket()) && addTo(byDay[d], r, pct)
+    const sid = r.sessionId || 'unknown'
+    ;(bySession[sid] ||= emptyBucket()) && addTo(bySession[sid], r, pct)
+    const m = r.model || 'unknown'
+    ;(byModel[m] ||= emptyBucket()) && addTo(byModel[m], r, pct)
+  }
+  const round = (n) => Math.round(n * 1e6) / 1e6
+  totalCostUsd = round(totalCostUsd)
+  const totalBilledUsd = round(num(applyMarkup(totalCostUsd, pct)))
+  for (const b of [...Object.values(byDay), ...Object.values(bySession), ...Object.values(byModel)]) {
+    b.costUsd = round(b.costUsd)
+    b.billedUsd = round(b.billedUsd)
+  }
+  return {
+    from: typeof from === 'number' ? from : null,
+    to: typeof to === 'number' ? to : null,
+    site: site || null,
+    markupPct: pct,
+    count: rows.length,
+    totalCostUsd,
+    totalBilledUsd,
+    totalTokens,
+    byDay,
+    bySession,
+    byModel,
+  }
+}
+
+export { appendCost, readCosts, readAll, rollup, normalizeEntry, estimateCostUsd, applyMarkup, defaultLogPath }

package/lib/vibe-orchestrator/src/ownerToken.js

@@ -0,0 +1,113 @@
+// ownerToken.js
+//
+// Real per-owner auth for the orchestrator (HAP-1109). Replaces the old
+// optional shared-secret gate, which failed OPEN when unset and could not tell
+// one caller from another.
+//
+// A vibe owner token is a compact, dependency-free, JWT-like string:
+//
+//   base64url(JSON(payload)) + "." + base64url(HMAC_SHA256(part1, secret))
+//
+// payload = { v:1, sub:<memberId>, roles:[...], site:<slug>, iat, exp }   (epoch seconds)
+//
+// The token is MINTED server-side by Mango from an authenticated admin session
+// (mango/endpoints -> mango/helpers/vibeToken.js, same format) and VERIFIED here
+// with a secret shared only between Mango and the orchestrator
+// (VIBE_ORCH_TOKEN_SECRET). The signature proves the claims were issued by Mango;
+// a non-owner cannot forge an admin role without the secret, and the client-side
+// role flag is no longer trusted. The Claude OAuth token is never involved.
+
+import crypto from 'node:crypto'
+
+const TOKEN_VERSION = 1
+
+function b64urlEncode(buf) {
+  return Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function b64urlDecode(str) {
+  const pad = str.length % 4 === 0 ? '' : '='.repeat(4 - (str.length % 4))
+  return Buffer.from(str.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64')
+}
+
+function sign(part, secret) {
+  return b64urlEncode(crypto.createHmac('sha256', secret).update(part).digest())
+}
+
+/** Constant-time string compare that never short-circuits on length. */
+function safeEqual(a, b) {
+  const ab = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  if (ab.length !== bb.length) {
+    // Still run a comparison to keep timing flat, then fail.
+    crypto.timingSafeEqual(ab, ab)
+    return false
+  }
+  return crypto.timingSafeEqual(ab, bb)
+}
+
+/**
+ * Mint an owner token. Used by tests/tooling; the production minter lives in
+ * Mango (mango/helpers/vibeToken.js) and MUST keep this exact format.
+ *
+ * @param {Object} opts
+ * @param {string} opts.secret               shared HMAC secret (required)
+ * @param {string} opts.sub                  member id
+ * @param {string[]} [opts.roles]            member roles
+ * @param {string} [opts.site]               site slug the token is scoped to
+ * @param {number} [opts.ttlSeconds=600]     lifetime
+ * @param {number} [opts.now]                epoch seconds (testing override)
+ */
+function mintOwnerToken({ secret, sub, roles = [], site = '', ttlSeconds = 600, now } = {}) {
+  if (!secret) throw new Error('mintOwnerToken: secret required')
+  if (!sub) throw new Error('mintOwnerToken: sub (member id) required')
+  const iat = Number.isFinite(now) ? Math.floor(now) : Math.floor(Date.now() / 1000)
+  const payload = { v: TOKEN_VERSION, sub: String(sub), roles: Array.isArray(roles) ? roles : [], site, iat, exp: iat + ttlSeconds }
+  const part = b64urlEncode(JSON.stringify(payload))
+  return `${part}.${sign(part, secret)}`
+}
+
+/**
+ * Verify an owner token. Returns { ok, payload } or { ok:false, reason, status }.
+ * status is the HTTP status the caller should surface (401 vs 403).
+ *
+ * @param {string} token
+ * @param {Object} opts
+ * @param {string} opts.secret               shared HMAC secret
+ * @param {string} [opts.site]               if set, token.site must match
+ * @param {string[]} [opts.ownerRoles]       roles that count as owner (default ['admin'])
+ * @param {number} [opts.now]                epoch seconds (testing override)
+ */
+function verifyOwnerToken(token, { secret, site, ownerRoles = ['admin'], now } = {}) {
+  if (!secret) return { ok: false, reason: 'owner auth not configured', status: 503 }
+  if (!token || typeof token !== 'string') return { ok: false, reason: 'missing token', status: 401 }
+
+  const dot = token.indexOf('.')
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: 'malformed token', status: 401 }
+  const part = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+
+  if (!safeEqual(sig, sign(part, secret))) return { ok: false, reason: 'bad signature', status: 401 }
+
+  let payload
+  try {
+    payload = JSON.parse(b64urlDecode(part).toString('utf8'))
+  } catch {
+    return { ok: false, reason: 'unparseable payload', status: 401 }
+  }
+  if (!payload || payload.v !== TOKEN_VERSION) return { ok: false, reason: 'unsupported token version', status: 401 }
+
+  const nowSec = Number.isFinite(now) ? Math.floor(now) : Math.floor(Date.now() / 1000)
+  if (typeof payload.exp !== 'number' || nowSec >= payload.exp) return { ok: false, reason: 'token expired', status: 401 }
+  if (typeof payload.iat === 'number' && nowSec + 60 < payload.iat) return { ok: false, reason: 'token not yet valid', status: 401 }
+
+  if (site && payload.site && payload.site !== site) return { ok: false, reason: 'token scoped to a different site', status: 403 }
+
+  const roles = Array.isArray(payload.roles) ? payload.roles : []
+  const isOwner = ownerRoles.some((r) => roles.includes(r))
+  if (!isOwner) return { ok: false, reason: 'not an owner', status: 403 }
+
+  return { ok: true, payload }
+}
+
+export { mintOwnerToken, verifyOwnerToken, TOKEN_VERSION }