@tpsdev-ai/flair 0.4.16 → 0.5.1

package/dist/resources/XAA.js

@@ -0,0 +1,264 @@
+import { databases } from "@harperfast/harper";
+import { createHash, randomBytes } from "node:crypto";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+/**
+ * XAA (Enterprise-Managed Authorization) — ID-JAG validation for Flair.
+ *
+ * Validates ID-JAG tokens from enterprise IdPs (Google Workspace, Azure AD,
+ * Okta) and issues Flair access tokens. Implements the jwt-bearer grant type
+ * (RFC 7523) at the OAuth token endpoint.
+ *
+ * Flow:
+ *   1. Client authenticates user via corporate SSO
+ *   2. IdP issues ID-JAG (signed JWT with policy decision)
+ *   3. Client presents ID-JAG to Flair's /OAuthToken endpoint
+ *   4. Flair validates signature, issuer, audience, domain, expiry, replay
+ *   5. Flair resolves or JIT-creates a Principal
+ *   6. Flair issues scoped access + refresh tokens
+ *
+ * Per FLAIR-XAA spec §§ 3-4.
+ */
+const ACCESS_TOKEN_TTL_MS = 3600_000; // 1 hour
+const REFRESH_TOKEN_TTL_MS = 7 * 86400_000; // 7 days
+const CLOCK_SKEW_MS = 30_000; // 30 seconds
+// JWKS remote key set cache per issuer (jose handles caching internally)
+const jwksSetCache = new Map();
+function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function randomToken(prefix) {
+    return `${prefix}${randomBytes(32).toString("base64url")}`;
+}
+function nowISO() {
+    return new Date().toISOString();
+}
+function futureISO(ms) {
+    return new Date(Date.now() + ms).toISOString();
+}
+/**
+ * Get or create a remote JWKS key set for an IdP.
+ * jose handles caching, key rotation, and refetching internally.
+ */
+function getJwksKeySet(jwksUri) {
+    let keySet = jwksSetCache.get(jwksUri);
+    if (!keySet) {
+        keySet = createRemoteJWKSet(new URL(jwksUri));
+        jwksSetCache.set(jwksUri, keySet);
+    }
+    return keySet;
+}
+/**
+ * Validate an ID-JAG token against a configured IdP.
+ * Returns the validated payload or throws with a specific error.
+ */
+export async function validateIdJag(assertion, expectedAudience) {
+    // Pre-decode to find the issuer (needed to look up the IdP config + JWKS URI)
+    const parts = assertion.split(".");
+    if (parts.length !== 3)
+        throw new Error("invalid JWT format");
+    let prePayload;
+    try {
+        prePayload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+    }
+    catch {
+        throw new Error("invalid JWT payload encoding");
+    }
+    const issuer = prePayload.iss;
+    if (!issuer)
+        throw new Error("missing iss claim");
+    // 2. Issuer lookup
+    let idpConfig = null;
+    for await (const cfg of databases.flair.IdpConfig.search({
+        conditions: [
+            { attribute: "issuer", comparator: "equals", value: issuer },
+            { attribute: "enabled", comparator: "equals", value: true },
+        ],
+    })) {
+        idpConfig = cfg;
+        break;
+    }
+    if (!idpConfig)
+        throw new Error(`unknown issuer: ${issuer}`);
+    // 1. Cryptographic signature verification via jose + IdP JWKS.
+    // This is the core security check — without it, all claims are forgeable.
+    // Sherlock's 2026-04-11 review finding: deferring signature verification
+    // defeats the entire purpose of JWTs.
+    const jwks = getJwksKeySet(idpConfig.jwksUri);
+    const { payload } = await jwtVerify(assertion, jwks, {
+        issuer,
+        audience: expectedAudience,
+        clockTolerance: CLOCK_SKEW_MS / 1000,
+    });
+    // 8. Domain restriction (post-verification — claims are now trusted)
+    if (idpConfig.requiredDomain) {
+        const hd = payload.hd;
+        const tid = payload.tid;
+        if (hd && hd !== idpConfig.requiredDomain) {
+            throw new Error(`domain mismatch: expected ${idpConfig.requiredDomain}, got ${hd}`);
+        }
+        if (tid && tid !== idpConfig.requiredDomain) {
+            throw new Error(`tenant mismatch: expected ${idpConfig.requiredDomain}, got ${tid}`);
+        }
+        if (!hd && !tid) {
+            throw new Error(`domain required but no hd/tid claim present — consumer account rejected`);
+        }
+    }
+    // Replay prevention (jti)
+    if (payload.jti) {
+        const existing = await databases.flair.IdJagReplay.get(payload.jti);
+        if (existing)
+            throw new Error("token replay detected");
+        const now = Date.now();
+        await databases.flair.IdJagReplay.put({
+            id: payload.jti,
+            expiresAt: futureISO(Math.max((payload.exp ?? 0) * 1000 - now + CLOCK_SKEW_MS, 300_000)),
+            createdAt: nowISO(),
+        });
+    }
+    return { payload: payload, idpConfig };
+}
+/**
+ * Resolve or JIT-create a Principal from validated ID-JAG claims.
+ */
+async function resolveOrCreatePrincipal(payload, idpConfig) {
+    const idpSubject = payload.sub;
+    const email = payload.email ?? payload.preferred_username;
+    const displayName = payload.name ?? email ?? idpSubject;
+    // Look for existing credential with this IdP subject
+    for await (const cred of databases.flair.Credential.search({
+        conditions: [
+            { attribute: "kind", comparator: "equals", value: "idp" },
+            { attribute: "idpSubject", comparator: "equals", value: idpSubject },
+            { attribute: "idpProvider", comparator: "equals", value: idpConfig.id },
+        ],
+    })) {
+        // Update last used
+        await databases.flair.Credential.put({
+            ...cred,
+            lastUsedAt: nowISO(),
+        });
+        return cred.principalId;
+    }
+    // No existing credential — JIT provision if enabled
+    if (!idpConfig.jitProvision) {
+        throw new Error(`no principal for IdP subject ${idpSubject} and JIT provisioning is disabled`);
+    }
+    const principalId = `usr_${idpSubject.replace(/[^a-zA-Z0-9]/g, "_").slice(0, 20)}_${randomBytes(4).toString("hex")}`;
+    const now = nowISO();
+    // Create principal (via Agent table)
+    await databases.flair.Agent.put({
+        id: principalId,
+        name: displayName,
+        displayName,
+        kind: "human",
+        type: "human",
+        status: "active",
+        publicKey: `idp:${idpConfig.id}:${idpSubject}`, // placeholder — humans don't have real Ed25519 keys
+        defaultTrustTier: idpConfig.defaultTrustTier ?? "unverified",
+        admin: false,
+        createdAt: now,
+        updatedAt: now,
+    });
+    // Create IdP credential
+    await databases.flair.Credential.put({
+        id: `cred_idp_${randomBytes(8).toString("hex")}`,
+        principalId,
+        kind: "idp",
+        label: idpConfig.name,
+        status: "active",
+        idpProvider: idpConfig.id,
+        idpSubject,
+        idpEmail: email,
+        createdAt: now,
+        lastUsedAt: now,
+    });
+    return principalId;
+}
+/**
+ * Handle the jwt-bearer grant type at the token endpoint.
+ * Called from OAuthToken when grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer.
+ */
+export async function handleJwtBearerGrant(data) {
+    const assertion = data?.assertion;
+    if (!assertion) {
+        return new Response(JSON.stringify({
+            error: "invalid_request",
+            error_description: "assertion parameter required for jwt-bearer grant",
+        }), { status: 400, headers: { "content-type": "application/json" } });
+    }
+    const baseUrl = process.env.FLAIR_PUBLIC_URL || `http://127.0.0.1:${process.env.HTTP_PORT || 19926}`;
+    try {
+        const { payload, idpConfig } = await validateIdJag(assertion, baseUrl);
+        // Resolve or create principal
+        const principalId = await resolveOrCreatePrincipal(payload, idpConfig);
+        // Determine scopes — intersection of ID-JAG scopes and IdP allowed scopes
+        const requestedScopes = (payload.scope ?? "memory:read").split(" ");
+        const allowedScopes = idpConfig.allowedScopes?.length
+            ? new Set(idpConfig.allowedScopes)
+            : null;
+        const grantedScopes = allowedScopes
+            ? requestedScopes.filter((s) => allowedScopes.has(s))
+            : requestedScopes;
+        const scope = grantedScopes.join(" ");
+        // Issue tokens
+        const now = nowISO();
+        const clientId = data?.client_id ?? idpConfig.clientId;
+        const accessTokenRaw = randomToken("flair_at_");
+        const refreshTokenRaw = randomToken("flair_rt_");
+        const accessId = `at_${randomBytes(8).toString("hex")}`;
+        const refreshId = `rt_${randomBytes(8).toString("hex")}`;
+        await databases.flair.OAuthToken.put({
+            id: accessId,
+            tokenHash: sha256(accessTokenRaw),
+            tokenType: "access",
+            clientId,
+            principalId,
+            scope,
+            expiresAt: futureISO(ACCESS_TOKEN_TTL_MS),
+            idpIssuer: payload.iss,
+            idpSubject: payload.sub,
+            createdAt: now,
+        });
+        await databases.flair.OAuthToken.put({
+            id: refreshId,
+            tokenHash: sha256(refreshTokenRaw),
+            tokenType: "refresh",
+            clientId,
+            principalId,
+            scope,
+            expiresAt: futureISO(REFRESH_TOKEN_TTL_MS),
+            parentTokenId: accessId,
+            idpIssuer: payload.iss,
+            idpSubject: payload.sub,
+            createdAt: now,
+        });
+        return {
+            access_token: accessTokenRaw,
+            token_type: "Bearer",
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: refreshTokenRaw,
+            scope,
+        };
+    }
+    catch (err) {
+        return new Response(JSON.stringify({
+            error: "invalid_grant",
+            error_description: err.message,
+        }), { status: 400, headers: { "content-type": "application/json" } });
+    }
+}
+/**
+ * IdP management resource — CRUD for IdP configurations.
+ * Admin-only access.
+ */
+export class IdpConfig extends databases.flair.IdpConfig {
+    async put(content) {
+        const now = nowISO();
+        content.enabled ??= true;
+        content.jitProvision ??= true;
+        content.defaultTrustTier ??= "unverified";
+        content.createdAt ??= now;
+        content.updatedAt = now;
+        return super.put(content);
+    }
+}

package/dist/resources/admin-layout.js

@@ -0,0 +1,94 @@
+/**
+ * Shared HTML layout for the Flair web admin.
+ * Server-rendered, no JS framework. Minimal CSS for Nathan-grade UX.
+ */
+const VERSION = process.env.npm_package_version ?? "dev";
+/** Escape HTML special characters to prevent stored XSS. */
+export function esc(str) {
+    if (!str)
+        return "";
+    return String(str)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+export function layout(title, content, activePage) {
+    const nav = [
+        { href: "/AdminDashboard", label: "Home", id: "home" },
+        { href: "/AdminMemory", label: "Memory", id: "memory" },
+        { href: "/AdminPrincipals", label: "Principals", id: "principals" },
+        { href: "/AdminConnectors", label: "Connectors", id: "connectors" },
+        { href: "/AdminIdp", label: "IdP", id: "idp" },
+        { href: "/AdminInstance", label: "Instance", id: "instance" },
+    ];
+    const navHtml = nav.map(n => `<a href="${n.href}" class="nav-item${activePage === n.id ? " active" : ""}">${n.label}</a>`).join("\n        ");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title} — Flair Admin</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui, -apple-system, sans-serif; background: #f8f9fa; color: #1a1a1a; }
+    .layout { display: flex; min-height: 100vh; }
+    .sidebar {
+      width: 220px; background: #1a1a2e; color: #e0e0e0; padding: 20px 0;
+      display: flex; flex-direction: column; flex-shrink: 0;
+    }
+    .sidebar-brand { padding: 0 20px 20px; font-size: 1.3em; font-weight: 700; color: #fff; border-bottom: 1px solid #2a2a4e; }
+    .nav-item {
+      display: block; padding: 10px 20px; color: #b0b0c0; text-decoration: none;
+      font-size: 0.95em; transition: background 0.15s;
+    }
+    .nav-item:hover { background: #2a2a4e; color: #fff; }
+    .nav-item.active { background: #2563eb; color: #fff; font-weight: 600; }
+    .main { flex: 1; padding: 32px 40px; max-width: 1100px; }
+    .main h1 { font-size: 1.6em; margin-bottom: 8px; }
+    .main .subtitle { color: #666; margin-bottom: 24px; }
+    table { width: 100%; border-collapse: collapse; background: #fff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+    th { text-align: left; padding: 12px 16px; background: #f1f3f5; font-size: 0.85em; color: #555; text-transform: uppercase; letter-spacing: 0.5px; }
+    td { padding: 12px 16px; border-top: 1px solid #eee; font-size: 0.95em; }
+    tr:hover td { background: #f8f9ff; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 10px; font-size: 0.8em; font-weight: 600; }
+    .badge-green { background: #d4edda; color: #155724; }
+    .badge-gray { background: #e9ecef; color: #495057; }
+    .badge-blue { background: #cce5ff; color: #004085; }
+    .badge-yellow { background: #fff3cd; color: #856404; }
+    .card { background: #fff; border-radius: 8px; padding: 20px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); margin-bottom: 16px; }
+    .card h3 { font-size: 1.1em; margin-bottom: 8px; }
+    .card .value { font-size: 2em; font-weight: 700; color: #2563eb; }
+    .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-bottom: 32px; }
+    .empty { text-align: center; padding: 40px; color: #888; }
+    .btn { display: inline-block; padding: 8px 16px; border-radius: 6px; font-size: 0.9em; text-decoration: none; cursor: pointer; border: none; }
+    .btn-primary { background: #2563eb; color: #fff; }
+    .btn-danger { background: #dc3545; color: #fff; }
+    .footer { padding: 20px; margin-top: auto; font-size: 0.8em; color: #666; border-top: 1px solid #2a2a4e; }
+    @media (max-width: 768px) {
+      .sidebar { width: 60px; } .sidebar-brand { display: none; } .nav-item { padding: 10px; text-align: center; font-size: 0.8em; }
+      .main { padding: 16px; }
+    }
+  </style>
+</head>
+<body>
+  <div class="layout">
+    <nav class="sidebar">
+      <div class="sidebar-brand">Flair</div>
+      ${navHtml}
+      <div class="footer">v${VERSION}</div>
+    </nav>
+    <main class="main">
+      ${content}
+    </main>
+  </div>
+</body>
+</html>`;
+}
+export function htmlResponse(html) {
+    return new Response(html, {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+    });
+}

package/dist/resources/auth-middleware.js

@@ -7,29 +7,26 @@ import { getEmbedding } from "./embeddings-provider.js";
 //
 // FLAIR_ADMIN_TOKEN env var is still accepted for backwards compat but
 // emits a deprecation warning on first use.
-let _adminPass = null;
+//
+// No permanent cache — env vars are read on every call. This is a no-op
+// performance-wise (env reads are fast) but means a process restart with a
+// different password works immediately without stale state.
 let _deprecationWarned = false;
 function getAdminPass() {
-    if (_adminPass)
-        return _adminPass;
     // Primary source: Harper's own admin password (set at startup via env)
     const primary = process.env.HDB_ADMIN_PASSWORD ?? process.env.FLAIR_ADMIN_PASSWORD;
-    if (primary) {
-        _adminPass = primary;
-        return _adminPass;
-    }
+    if (primary)
+        return primary;
     // Backwards compat: FLAIR_ADMIN_TOKEN (deprecated — never write to disk)
     if (process.env.FLAIR_ADMIN_TOKEN) {
         if (!_deprecationWarned) {
             console.warn("[auth] DEPRECATION: FLAIR_ADMIN_TOKEN is deprecated. Use HDB_ADMIN_PASSWORD instead.");
             _deprecationWarned = true;
         }
-        _adminPass = process.env.FLAIR_ADMIN_TOKEN;
-        return _adminPass;
+        return process.env.FLAIR_ADMIN_TOKEN;
     }
-    const msg = "[auth] FATAL: no admin password found. Set HDB_ADMIN_PASSWORD env var.";
-    console.error(msg);
-    throw new Error(msg);
+    // No admin password configured — return null and let callers fall through
+    return null;
 }
 const WINDOW_MS = 30_000;
 const nonceSeen = new Map();
@@ -119,7 +116,17 @@ server.http(async (request, nextLayer) => {
         url.pathname === "/A2AAdapter" ||
         url.pathname === "/AgentCard" ||
         url.pathname.startsWith("/A2AAdapter/") ||
-        url.pathname.startsWith("/AgentCard/"))
+        url.pathname.startsWith("/AgentCard/") ||
+        // Federation endpoints handle their own auth via Ed25519 body signatures
+        url.pathname === "/FederationPair" ||
+        url.pathname === "/FederationSync" ||
+        // OAuth 2.1 public endpoints (spec requires no pre-auth)
+        url.pathname === "/OAuthRegister" ||
+        url.pathname === "/OAuthAuthorize" ||
+        url.pathname === "/OAuthToken" ||
+        url.pathname === "/OAuthRevoke" ||
+        url.pathname === "/.well-known/oauth-authorization-server" ||
+        url.pathname === "/OAuthMetadata")
         return nextLayer(request);
     // Skip re-entry: if we already swapped auth to Basic, pass through
     if (request._tpsAuthVerified)
@@ -132,7 +139,8 @@ server.http(async (request, nextLayer) => {
         try {
             const decoded = Buffer.from(header.slice(6), "base64").toString("utf-8");
             const [user, pass] = decoded.split(":");
-            if (user === "admin" && pass === getAdminPass()) {
+            const adminPass = getAdminPass();
+            if (adminPass !== null && user === "admin" && pass === adminPass) {
                 // Mark as verified and set Harper user directly
                 request._tpsAuthVerified = true;
                 try {
@@ -187,14 +195,24 @@ server.http(async (request, nextLayer) => {
     // pipeline (passport) authenticates the request with full permissions including
     // HNSW vector search. This requires HDB_ADMIN_PASSWORD to be set.
     // NOTE: server.getUser() alone doesn't grant HNSW permissions in Harper v5.
-    try {
-        const superAuth = "Basic " + btoa("admin:" + getAdminPass());
-        request.headers.set("authorization", superAuth);
-        if (request.headers.asObject)
-            request.headers.asObject.authorization = superAuth;
+    const adminPass = getAdminPass();
+    if (adminPass !== null) {
+        try {
+            const superAuth = "Basic " + btoa("admin:" + adminPass);
+            request.headers.set("authorization", superAuth);
+            if (request.headers.asObject)
+                request.headers.asObject.authorization = superAuth;
+        }
+        catch {
+            // Header manipulation failed — fall back to getUser
+            try {
+                request.user = await server.getUser("admin", null, request);
+            }
+            catch { }
+        }
     }
-    catch {
-        // No admin password — try server.getUser as fallback (limited permissions)
+    else {
+        // No admin password configured — try server.getUser as fallback (limited permissions)
         try {
             request.user = await server.getUser("admin", null, request);
         }

package/dist/resources/embeddings-provider.js

@@ -3,28 +3,28 @@
  *
  * Wrapper around harper-fabric-embeddings for Flair resources.
  *
- * Harper loads resources in a VM sandbox with a separate module cache from
- * the main thread. This means our import of harper-fabric-embeddings gets
- * a different (uninitialized) instance from the one Harper initialized via
- * handleApplication in config.yaml.
- *
- * Solution: we call hfe.init() ourselves on first use. The model is already
- * on disk (downloaded by Harper's plugin loader), so init just loads the
- * native binary and model file — no download needed.
+ * Harper 5.0.0 loads resources in a VM sandbox that can't statically link
+ * npm packages during module resolution (async race in getOrCreateModule).
+ * Using dynamic import() defers the module load to first use, bypassing
+ * the VM linker entirely.
  */
-import * as hfe from "harper-fabric-embeddings";
 import { join } from "node:path";
 let _state = "uninitialized";
 let _initError;
 let _warnedOnce = false;
+let _hfe = null;
 async function ensureInit() {
     if (_state === "ready")
         return;
     if (_state === "failed")
         return; // Don't retry — already logged warning
     try {
+        // Dynamic import — deferred to avoid Harper 5.0.0 VM linker race
+        if (!_hfe) {
+            _hfe = await import("harper-fabric-embeddings");
+        }
         // Check if already initialized (e.g. shared context)
-        hfe.dimensions();
+        _hfe.dimensions();
         _state = "ready";
         return;
     }
@@ -35,6 +35,9 @@ async function ensureInit() {
         // VM sandbox / worker threads, so we use process.cwd() which points to the
         // Flair application directory.
         try {
+            if (!_hfe) {
+                _hfe = await import("harper-fabric-embeddings");
+            }
             const modelsDir = join(process.cwd(), "models");
             // Find the native addon binary explicitly to avoid __dirname-dependent
             // discovery in @node-llama-cpp which fails in Harper's VM sandbox.
@@ -48,7 +51,7 @@ async function ensureInit() {
                     break;
                 }
             }
-            await hfe.init({ modelsDir, ...(addonPath ? { addonPath } : {}) });
+            await _hfe.init({ modelsDir, ...(addonPath ? { addonPath } : {}) });
             _state = "ready";
         }
         catch (err) {
@@ -68,18 +71,15 @@ async function ensureInit() {
 export async function getEmbedding(text) {
     try {
         await ensureInit();
-        if (_state !== "ready")
+        if (_state !== "ready" || !_hfe)
             return null;
-        return await hfe.embed(text);
+        return await _hfe.embed(text);
     }
     catch (err) {
         console.error(`[embeddings] embed failed: ${err.message}`);
         return null;
     }
 }
-/**
- * Check if the embedding engine is currently available.
- */
 /**
  * Check if the embedding engine is currently available.
  * If still uninitialized, attempts initialization first.
@@ -93,20 +93,23 @@ export function getMode() {
     if (_state === "failed")
         return "none";
     // Still uninitialized — try direct check first
-    try {
-        hfe.dimensions();
-        _state = "ready";
-        return "local";
-    }
-    catch {
-        // Not yet initialized. Trigger async init on first call so subsequent
-        // calls (including getEmbedding) will find the engine ready.
-        if (!_getModeInitAttempted) {
-            _getModeInitAttempted = true;
-            ensureInit().catch(() => { }); // fire-and-forget
+    if (_hfe) {
+        try {
+            _hfe.dimensions();
+            _state = "ready";
+            return "local";
         }
-        return "none";
+        catch {
+            // fall through
+        }
+    }
+    // Not yet initialized. Trigger async init on first call so subsequent
+    // calls (including getEmbedding) will find the engine ready.
+    if (!_getModeInitAttempted) {
+        _getModeInitAttempted = true;
+        ensureInit().catch(() => { }); // fire-and-forget
     }
+    return "none";
 }
 /**
  * Get the current embedding model identifier.
@@ -120,12 +123,12 @@ export function getModelId() {
  */
 export function getStatus() {
     const mode = getMode();
-    if (mode === "local") {
+    if (mode === "local" && _hfe) {
         try {
             return {
                 mode,
                 model: "nomic-embed-text-v1.5",
-                dims: hfe.dimensions(),
+                dims: _hfe.dimensions(),
             };
         }
         catch {

package/dist/resources/federation-crypto.js

@@ -0,0 +1,52 @@
+/**
+ * Federation cryptographic utilities — pure functions, no HarperDB dependency.
+ * Shared by Federation.ts (server) and cli.ts (client).
+ */
+import nacl from "tweetnacl";
+// ─── Canonical JSON ─────────────────────────────────────────────────────────
+/**
+ * Deterministic JSON serialization: recursively sort object keys, then stringify.
+ * Used as the signing input for federation requests.
+ */
+export function canonicalize(obj) {
+    return JSON.stringify(sortKeys(obj));
+}
+function sortKeys(val) {
+    if (val === null || val === undefined || typeof val !== "object")
+        return val;
+    if (Array.isArray(val))
+        return val.map(sortKeys);
+    const sorted = {};
+    for (const key of Object.keys(val).sort()) {
+        sorted[key] = sortKeys(val[key]);
+    }
+    return sorted;
+}
+// ─── Signing ────────────────────────────────────────────────────────────────
+/**
+ * Create a detached Ed25519 signature over the canonical form of a body.
+ * Returns base64url-encoded signature.
+ */
+export function signBody(body, secretKey) {
+    const message = new TextEncoder().encode(canonicalize(body));
+    const sig = nacl.sign.detached(message, secretKey);
+    return Buffer.from(sig).toString("base64url");
+}
+/**
+ * Verify a signature field on a request body.
+ * The canonical form is the body WITHOUT the `signature` field.
+ */
+export function verifyBodySignature(body, publicKeyB64url) {
+    const { signature, ...rest } = body;
+    if (!signature)
+        return false;
+    try {
+        const message = new TextEncoder().encode(canonicalize(rest));
+        const sig = Buffer.from(signature, "base64url");
+        const pubKey = Buffer.from(publicKeyB64url, "base64url");
+        return nacl.sign.detached.verify(message, new Uint8Array(sig), new Uint8Array(pubKey));
+    }
+    catch {
+        return false;
+    }
+}