@grapity/grapity 0.3.0 → 0.4.1

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 
 // src/cli/commands/registry/index.ts
 import { Command as Command8 } from "commander";
@@ -18,6 +18,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import yaml from "js-yaml";
+var CONFIG_PATH = () => path.join(os.homedir(), ".grapity", "config.yaml");
 var DEFAULT_CONFIG = {
   mode: "local",
   local: {
@@ -25,8 +26,11 @@ var DEFAULT_CONFIG = {
     database: "sqlite"
   }
 };
+function configExists() {
+  return fs.existsSync(CONFIG_PATH());
+}
 function getConfig() {
-  const configPath = path.join(os.homedir(), ".grapity", "config.yaml");
+  const configPath = CONFIG_PATH();
   if (!fs.existsSync(configPath)) {
     return DEFAULT_CONFIG;
   }
@@ -52,7 +56,8 @@ function getConfig() {
       port: config.local?.port ?? DEFAULT_CONFIG.local.port,
       database,
       sqlitePath: config.local?.sqlitePath,
-      postgresUrl: config.local?.postgresUrl
+      postgresUrl: config.local?.postgresUrl,
+      auth: config.local?.auth
     }
   };
 }
@@ -67,6 +72,169 @@ function isPostgresqlUrl(value) {
   return value.startsWith("postgresql://") || value.startsWith("postgres://");
 }
 
+// src/cli/auth.ts
+import { decodeJwt } from "jose";
+
+// src/registry/auth/middleware.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+var AuthError = class extends Error {
+  constructor(statusCode, code, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.name = "AuthError";
+  }
+  statusCode;
+  code;
+};
+function buildKeycloakUrls(config) {
+  const base = `${config.serverUrl}/realms/${config.realm}`;
+  return {
+    issuer: base,
+    jwksUri: `${base}/protocol/openid-connect/certs`,
+    tokenUrl: `${base}/protocol/openid-connect/token`
+  };
+}
+function createAuthMiddleware(config, routeScopes2) {
+  if (config.auth?.mode !== "keycloak") {
+    return async (_c, next) => await next();
+  }
+  const authConfig = config.auth;
+  const { issuer, jwksUri } = buildKeycloakUrls(authConfig);
+  const jwks = createRemoteJWKSet(new URL(jwksUri));
+  const scopeByRoute = /* @__PURE__ */ new Map();
+  for (const route of routeScopes2) {
+    const key = `${route.method.toUpperCase()}:${route.path}`;
+    scopeByRoute.set(key, {
+      operationId: route.operationId,
+      scopes: route.scopes
+    });
+  }
+  return async (c2, next) => {
+    const matchedPath = c2.req.matchedRoutes.map((r) => r.path).filter((p) => p !== "/*").pop();
+    const routeKey = matchedPath ? `${c2.req.method}:${matchedPath}` : `${c2.req.method}:${c2.req.routePath}`;
+    const required = scopeByRoute.get(routeKey);
+    if (!required || required.scopes.length === 0) {
+      return await next();
+    }
+    const authHeader = c2.req.header("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      throw new AuthError(401, "unauthorized", "Bearer token required");
+    }
+    const token = authHeader.slice("Bearer ".length).trim();
+    if (!token) {
+      throw new AuthError(401, "unauthorized", "Bearer token required");
+    }
+    let payload;
+    try {
+      const result = await jwtVerify(token, jwks, {
+        issuer,
+        audience: authConfig.audience
+      });
+      payload = result.payload;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Invalid token";
+      throw new AuthError(401, "unauthorized", `Invalid or expired token: ${message}`);
+    }
+    const subject = payload.sub;
+    if (!subject) {
+      throw new AuthError(401, "unauthorized", "Token missing subject claim");
+    }
+    const grantedScopes = extractScopes(payload, authConfig.roleSource ?? "scope");
+    const missing = required.scopes.filter((s) => !grantedScopes.has(s));
+    if (missing.length > 0) {
+      throw new AuthError(
+        403,
+        "forbidden",
+        `Missing required scope${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`
+      );
+    }
+    c2.set("actor", subject);
+    c2.set("claims", payload);
+    await next();
+  };
+}
+function extractScopes(payload, source) {
+  if (source === "realm_access.roles") {
+    const roles = payload.realm_access?.roles;
+    return new Set(roles ?? []);
+  }
+  const scopeValue = payload.scope;
+  if (typeof scopeValue === "string") {
+    return new Set(scopeValue.split(/\s+/).filter(Boolean));
+  }
+  return /* @__PURE__ */ new Set();
+}
+
+// src/cli/auth.ts
+var cachedToken = null;
+function resetTokenCache() {
+  cachedToken = null;
+}
+async function getAccessToken(config) {
+  const staticToken = process.env.GRAPITY_TOKEN;
+  if (staticToken) {
+    return staticToken;
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (cachedToken && cachedToken.expiresAt > now + 60) {
+    return cachedToken.accessToken;
+  }
+  const clientSecret = process.env.GRAPITY_CLIENT_SECRET;
+  if (!clientSecret) {
+    throw new Error(
+      "Keycloak client secret not found. Set GRAPITY_CLIENT_SECRET or provide a static token via GRAPITY_TOKEN."
+    );
+  }
+  const { tokenUrl } = buildKeycloakUrls({ serverUrl: config.serverUrl, realm: config.realm });
+  const params = new URLSearchParams();
+  params.set("grant_type", "client_credentials");
+  params.set("client_id", config.clientId);
+  params.set("client_secret", clientSecret);
+  if (config.audience) {
+    params.set("audience", config.audience);
+  }
+  const response = await fetch(tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: params.toString()
+  });
+  if (!response.ok) {
+    const text3 = await response.text().catch(() => "Unknown error");
+    throw new Error(`Keycloak token request failed: ${response.status} ${text3}`);
+  }
+  const data = await response.json();
+  cachedToken = {
+    accessToken: data.access_token,
+    expiresAt: now + data.expires_in
+  };
+  return data.access_token;
+}
+function decodeToken(token) {
+  try {
+    const payload = decodeJwt(token);
+    return {
+      sub: payload.sub,
+      exp: payload.exp,
+      iss: payload.iss,
+      scope: typeof payload.scope === "string" ? payload.scope : void 0,
+      roles: payload.realm_access?.roles
+    };
+  } catch {
+    return {};
+  }
+}
+function formatTokenStatus(token) {
+  const decoded = decodeToken(token);
+  const now = Math.floor(Date.now() / 1e3);
+  return {
+    valid: !!decoded.sub,
+    sub: decoded.sub,
+    exp: decoded.exp,
+    expired: decoded.exp ? decoded.exp < now : void 0
+  };
+}
+
 // src/cli/client.ts
 var BreakingChangeError = class extends Error {
   constructor(compatReport) {
@@ -76,13 +244,30 @@ var BreakingChangeError = class extends Error {
   }
   compatReport;
 };
+async function getAuthHeaders() {
+  const config = getConfig();
+  const authConfig = config.mode === "remote" ? config.remote?.auth : config.local?.auth;
+  const headers = {};
+  if (authConfig?.mode === "keycloak") {
+    if (!authConfig.clientId) {
+      throw new Error(
+        "Keycloak auth is configured but clientId is missing. Run grapity init with --keycloak-client-id."
+      );
+    }
+    const token = await getAccessToken(authConfig);
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  return headers;
+}
 async function request(method, path12, body) {
   const baseUrl = getRegistryUrl();
   const url = `${baseUrl}${path12}`;
+  const authHeaders = await getAuthHeaders();
   const response = await fetch(url, {
     method,
     headers: {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      ...authHeaders
     },
     body: body ? JSON.stringify(body) : void 0
   });
@@ -99,7 +284,11 @@ async function request(method, path12, body) {
 async function requestText(method, path12) {
   const baseUrl = getRegistryUrl();
   const url = `${baseUrl}${path12}`;
-  const response = await fetch(url, { method });
+  const authHeaders = await getAuthHeaders();
+  const response = await fetch(url, {
+    method,
+    headers: authHeaders
+  });
   if (!response.ok) {
     const error = await response.json();
     throw new Error(error.message ?? `Request failed: ${response.status}`);
@@ -534,12 +723,24 @@ function formatInitSuccess(params) {
     if (params.database) lines.push(`  ${c.label("Database")}  ${c.primary(params.database)}`);
     if (params.dbPath) lines.push(`  ${c.label("Path")}  ${c.dim(params.dbPath)}`);
     if (params.postgresUrl) lines.push(`  ${c.label("PostgreSQL")}  ${c.dim(params.postgresUrl)}`);
-    lines.push("");
-    lines.push(`  ${c.dim("\u203A")} Start the server with:  ${c.primary("grapity serve")}`);
   } else {
     if (params.url) lines.push(`  ${c.label("URL")}  ${c.cyan(params.url)}`);
+  }
+  if (params.authMode && params.authMode !== "none") {
+    lines.push("");
+    lines.push(`  ${c.label("Auth")}  ${c.primary(params.authMode)}`);
+    if (params.keycloakServer) lines.push(`  ${c.label("Keycloak")}  ${c.dim(params.keycloakServer)}`);
+    if (params.keycloakRealm) lines.push(`  ${c.label("Realm")}  ${c.dim(params.keycloakRealm)}`);
+    if (params.keycloakClientId) lines.push(`  ${c.label("Client ID")}  ${c.dim(params.keycloakClientId)}`);
+    lines.push("");
+    lines.push(`  ${c.dim("\u203A")} Set the client secret in GRAPITY_CLIENT_SECRET before running commands.`);
+  } else {
     lines.push("");
-    lines.push(`  ${c.dim("\u203A")} Push a spec with:  ${c.primary("grapity registry push ./openapi.yaml --name my-api")}`);
+    if (params.mode === "local") {
+      lines.push(`  ${c.dim("\u203A")} Start the server with:  ${c.primary("grapity serve")}`);
+    } else {
+      lines.push(`  ${c.dim("\u203A")} Push a spec with:  ${c.primary("grapity registry push ./openapi.yaml --name my-api")}`);
+    }
   }
   return lines.join("\n");
 }
@@ -555,6 +756,16 @@ function formatServeConfig(params) {
   if (params.database === "postgresql" && params.postgresUrl) {
     lines.push(`  ${c.label("PostgreSQL")}  ${c.dim(maskPostgresUrl(params.postgresUrl))}`);
   }
+  lines.push(`  ${c.label("Auth")}      ${c.primary(params.authMode ?? "none")}`);
+  if (params.keycloakServer) {
+    lines.push(`  ${c.label("Keycloak")}  ${c.dim(params.keycloakServer)}`);
+  }
+  if (params.keycloakRealm) {
+    lines.push(`  ${c.label("Realm")}     ${c.dim(params.keycloakRealm)}`);
+  }
+  if (params.keycloakAudience) {
+    lines.push(`  ${c.label("Audience")}  ${c.dim(params.keycloakAudience)}`);
+  }
   return lines.join("\n");
 }
 function maskPostgresUrl(url) {
@@ -598,6 +809,39 @@ function formatEmptyState(message, hints) {
 function formatReady(port) {
   return `  ${c.success("\u25CF")}  Server ready  ${c.label("\xB7")}  ${c.cyan(`http://localhost:${port}`)}`;
 }
+function formatAuthStatus(params) {
+  const lines = [];
+  if (params.cleared) {
+    lines.push(`  ${c.success("\u2713")} Cached access token cleared`);
+    return lines.join("\n");
+  }
+  lines.push(`  ${c.label("Mode")}  ${c.primary(params.mode)}`);
+  if (!params.configured) {
+    lines.push(`  ${c.dim("\xB7")} No remote authentication configured`);
+    return lines.join("\n");
+  }
+  if (params.serverUrl) lines.push(`  ${c.label("Server")}  ${c.dim(params.serverUrl)}`);
+  if (params.realm) lines.push(`  ${c.label("Realm")}  ${c.dim(params.realm)}`);
+  if (params.clientId) lines.push(`  ${c.label("Client ID")}  ${c.dim(params.clientId)}`);
+  if (params.audience) lines.push(`  ${c.label("Audience")}  ${c.dim(params.audience)}`);
+  lines.push("");
+  if (params.valid === false) {
+    lines.push(`  ${c.error("\u2717")} Token is not a valid JWT`);
+  } else if (params.sub) {
+    lines.push(`  ${c.success("\u2713")} Authenticated as ${c.primary(params.sub)}`);
+    if (params.exp) {
+      const date = new Date(params.exp * 1e3).toISOString();
+      if (params.expired) {
+        lines.push(`  ${c.error("\u2717")} Token expired at ${c.dim(date)}`);
+      } else {
+        lines.push(`  ${c.success("\u2713")} Token valid until ${c.dim(date)}`);
+      }
+    }
+  } else {
+    lines.push(`  ${c.dim("\xB7")} No token fetched yet`);
+  }
+  return lines.join("\n");
+}
 function formatHubReady(port) {
   return `  ${c.success("\u25CF")}  Hub ready     ${c.label("\xB7")}  ${c.cyan(`http://localhost:${port}`)}`;
 }
@@ -1396,7 +1640,7 @@ import fs8 from "fs";
 import os3 from "os";
 import path8 from "path";
 import yaml4 from "js-yaml";
-var initCommand = new Command18("init").description("Configure grapity registry (local or remote mode)").option("--local", "Use local mode (SQLite or PostgreSQL)").option("--remote", "Use remote mode (connect to a grapity server)").option("--url <url>", "Registry URL (for remote mode)").option("--port <port>", "Port for local server (default: 3750)").option("--db <path-or-url>", "SQLite path or postgresql:// URL (for local mode)").action(async (options) => {
+var initCommand = new Command18("init").description("Configure grapity registry (local or remote mode)").option("--local", "Use local mode (SQLite or PostgreSQL)").option("--remote", "Use remote mode (connect to a grapity server)").option("--url <url>", "Registry URL (for remote mode)").option("--port <port>", "Port for local server (default: 3750)").option("--db <path-or-url>", "SQLite path or postgresql:// URL (for local mode)").option("--auth <mode>", "Auth mode: none | keycloak (default: none)").option("--keycloak-server <url>", "Keycloak server URL").option("--keycloak-realm <realm>", "Keycloak realm").option("--keycloak-client-id <id>", "Keycloak client ID (for CLI client credentials)").option("--keycloak-audience <audience>", "Keycloak token audience to validate").option("--keycloak-role-source <source>", "Where to read roles from: scope | realm_access.roles (default: scope)").action(async (options) => {
   const configDir = path8.join(os3.homedir(), ".grapity");
   const configPath = path8.join(configDir, "config.yaml");
   let mode;
@@ -1421,6 +1665,12 @@ var initCommand = new Command18("init").description("Configure grapity registry
     );
     process.exit(1);
   }
+  const authMode = options.auth ?? "none";
+  if (authMode !== "none" && authMode !== "keycloak") {
+    console.error(formatError("invalid auth mode", "--auth must be one of: none, keycloak"));
+    process.exit(1);
+  }
+  const keycloakAuth = authMode === "keycloak" ? parseKeycloakOptions(options, mode) : void 0;
   const config = { mode };
   if (mode === "local") {
     const dbValue = options.db ?? process.env.GRAPITY_DATABASE_URL;
@@ -1434,6 +1684,22 @@ var initCommand = new Command18("init").description("Configure grapity registry
     } else {
       config.local.sqlitePath = dbValue ?? path8.join(os3.homedir(), ".grapity", "registry.db");
     }
+    if (keycloakAuth) {
+      if (!options.keycloakClientId) {
+        console.error(
+          formatError(
+            "missing flag",
+            "--keycloak-client-id is required when using Keycloak auth."
+          )
+        );
+        process.exit(1);
+      }
+      config.local.auth = {
+        mode: "keycloak",
+        clientId: options.keycloakClientId,
+        ...keycloakAuth
+      };
+    }
   } else {
     if (!options.url) {
       console.error(
@@ -1448,6 +1714,16 @@ var initCommand = new Command18("init").description("Configure grapity registry
     config.remote = {
       url: options.url.replace(/\/$/, "")
     };
+    if (keycloakAuth) {
+      config.remote.auth = {
+        mode: "keycloak",
+        serverUrl: keycloakAuth.serverUrl,
+        realm: keycloakAuth.realm,
+        clientId: keycloakAuth.clientId,
+        audience: keycloakAuth.audience,
+        roleSource: keycloakAuth.roleSource
+      };
+    }
   }
   if (!fs8.existsSync(configDir)) {
     fs8.mkdirSync(configDir, { recursive: true });
@@ -1462,16 +1738,107 @@ var initCommand = new Command18("init").description("Configure grapity registry
       database: config.local?.database,
       dbPath: config.local?.sqlitePath,
       postgresUrl: config.local?.postgresUrl,
-      url: config.remote?.url
+      url: config.remote?.url,
+      authMode,
+      keycloakServer: keycloakAuth?.serverUrl,
+      keycloakRealm: keycloakAuth?.realm,
+      keycloakClientId: config.local?.auth?.clientId ?? config.remote?.auth?.clientId
     })
   );
 });
+function parseKeycloakOptions(options, _mode) {
+  if (!options.keycloakServer) {
+    console.error(
+      formatError(
+        "missing flag",
+        "--keycloak-server is required when auth mode is keycloak.",
+        ["Example:  --keycloak-server https://keycloak.example.com"]
+      )
+    );
+    process.exit(1);
+  }
+  if (!options.keycloakRealm) {
+    console.error(
+      formatError(
+        "missing flag",
+        "--keycloak-realm is required when auth mode is keycloak.",
+        ["Example:  --keycloak-realm grapity"]
+      )
+    );
+    process.exit(1);
+  }
+  const roleSource = options.keycloakRoleSource;
+  if (roleSource && roleSource !== "scope" && roleSource !== "realm_access.roles") {
+    console.error(formatError("invalid role source", "--keycloak-role-source must be one of: scope, realm_access.roles"));
+    process.exit(1);
+  }
+  return {
+    serverUrl: options.keycloakServer.replace(/\/$/, ""),
+    realm: options.keycloakRealm,
+    clientId: options.keycloakClientId,
+    audience: options.keycloakAudience,
+    roleSource
+  };
+}
 
-// src/cli/commands/serve.ts
+// src/cli/commands/auth.ts
 import { Command as Command19 } from "commander";
+var authCommand = new Command19("auth").description("Manage authentication for remote registry mode").addCommand(
+  new Command19("status").description("Show current authentication status").action(async () => {
+    const config = getConfig();
+    const auth = config.mode === "remote" ? config.remote?.auth : config.local?.auth;
+    if (!auth) {
+      console.log(formatAuthStatus({ mode: "none", configured: false }));
+      return;
+    }
+    if (auth.mode !== "keycloak") {
+      console.log(formatAuthStatus({ mode: auth.mode, configured: true }));
+      return;
+    }
+    if (!auth.clientId) {
+      console.error(
+        formatError(
+          "auth misconfigured",
+          "Keycloak auth is configured but clientId is missing. Run grapity init with --keycloak-client-id."
+        )
+      );
+      process.exit(1);
+    }
+    try {
+      const token = await getAccessToken(auth);
+      const status = formatTokenStatus(token);
+      console.log(
+        formatAuthStatus({
+          mode: auth.mode,
+          configured: true,
+          serverUrl: auth.serverUrl,
+          realm: auth.realm,
+          clientId: auth.clientId,
+          audience: auth.audience,
+          ...status
+        })
+      );
+    } catch (err) {
+      console.error(
+        formatError(
+          "auth failed",
+          err instanceof Error ? err.message : "Unable to fetch access token"
+        )
+      );
+      process.exit(1);
+    }
+  })
+).addCommand(
+  new Command19("clear").description("Clear the cached access token").action(() => {
+    resetTokenCache();
+    console.log(formatAuthStatus({ mode: "none", configured: false, cleared: true }));
+  })
+);
+
+// src/cli/commands/serve.ts
+import { Command as Command20 } from "commander";
 import os4 from "os";
 import path11 from "path";
-import { readFileSync } from "fs";
 
 // src/registry/serve.ts
 import path9 from "path";
@@ -3231,6 +3598,7 @@ var pushRoute = new Hono().post("/", async (c2) => {
   }
   const store = c2.get("store");
   const service = new RegistryService(store);
+  const actor = c2.get("actor") ?? body.pushedBy;
   try {
     const result = await service.pushSpec(body.content, body.name, {
       type: body.type,
@@ -3239,7 +3607,7 @@ var pushRoute = new Hono().post("/", async (c2) => {
       sourceRepo: body.sourceRepo,
       tags: Array.isArray(body.tags) ? body.tags : void 0,
       gitRef: body.gitRef,
-      pushedBy: body.pushedBy,
+      pushedBy: actor,
       prerelease: body.prerelease,
       force: body.force,
       reason: body.reason
@@ -3404,7 +3772,8 @@ var deleteSpecRoute = new Hono5().delete(
     const name = c2.req.param("name");
     const store = c2.get("store");
     const service = new RegistryService(store);
-    const deleted = await service.deleteSpec(name);
+    const actor = c2.get("actor");
+    const deleted = await service.deleteSpec(name, actor);
     if (!deleted) {
       return c2.json({ error: "not_found", message: `Spec "${name}" not found`, statusCode: 404 }, 404);
     }
@@ -4145,6 +4514,7 @@ var pushGatewayConfigRoute = new Hono13().post("/", async (c2) => {
   }
   const store = c2.get("store");
   const service = new GatewayService(store, store);
+  const actor = c2.get("actor") ?? body.pushedBy;
   try {
     const result = await service.pushGatewayConfig({
       name: body.name,
@@ -4155,7 +4525,7 @@ var pushGatewayConfigRoute = new Hono13().post("/", async (c2) => {
       environments: body.environments ?? {},
       callerIdentification: body.callerIdentification,
       content: body.content,
-      pushedBy: body.pushedBy
+      pushedBy: actor
     });
     return c2.json({ data: result }, 201);
   } catch (err) {
@@ -4420,6 +4790,192 @@ var gatewayLogStatsRoute = new Hono21().get("/stats", async (c2) => {
   });
 });
 
+// src/registry/generated/route-scopes.ts
+var routeScopes = [
+  {
+    "method": "GET",
+    "path": "/v1/health",
+    "operationId": "getHealth",
+    "scopes": []
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs",
+    "operationId": "listSpecs",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "POST",
+    "path": "/v1/specs",
+    "operationId": "pushSpec",
+    "scopes": [
+      "specs:write"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name",
+    "operationId": "getSpec",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "DELETE",
+    "path": "/v1/specs/:name",
+    "operationId": "deleteSpec",
+    "scopes": [
+      "specs:write"
+    ]
+  },
+  {
+    "method": "POST",
+    "path": "/v1/specs/:name/validate",
+    "operationId": "validateSpec",
+    "scopes": [
+      "specs:write"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/versions",
+    "operationId": "listVersions",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/versions/:semver",
+    "operationId": "getVersion",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/spec.json",
+    "operationId": "getSpecJson",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/spec.yaml",
+    "operationId": "getSpecYaml",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/versions/:semver/spec.json",
+    "operationId": "getVersionSpecJson",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/versions/:semver/spec.yaml",
+    "operationId": "getVersionSpecYaml",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/compat/:semver",
+    "operationId": "getCompatReport",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/specs/:name/compare",
+    "operationId": "compareVersions",
+    "scopes": [
+      "specs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-configs",
+    "operationId": "listGatewayConfigs",
+    "scopes": [
+      "gateway-configs:read"
+    ]
+  },
+  {
+    "method": "POST",
+    "path": "/v1/gateway-configs",
+    "operationId": "pushGatewayConfig",
+    "scopes": [
+      "gateway-configs:write"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-configs/:name",
+    "operationId": "getGatewayConfig",
+    "scopes": [
+      "gateway-configs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-configs/:name/versions",
+    "operationId": "listGatewayConfigVersions",
+    "scopes": [
+      "gateway-configs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-configs/:name/versions/:versionId",
+    "operationId": "getGatewayConfigVersion",
+    "scopes": [
+      "gateway-configs:read"
+    ]
+  },
+  {
+    "method": "POST",
+    "path": "/v1/gateway-logs/ingest/:provider/:environment",
+    "operationId": "ingestGatewayLog",
+    "scopes": [
+      "gateway-logs:write"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-logs",
+    "operationId": "listGatewayLogs",
+    "scopes": [
+      "gateway-logs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-logs/stats",
+    "operationId": "getGatewayLogStats",
+    "scopes": [
+      "gateway-logs:read"
+    ]
+  },
+  {
+    "method": "GET",
+    "path": "/v1/gateway-logs/:id",
+    "operationId": "getGatewayLog",
+    "scopes": [
+      "gateway-logs:read"
+    ]
+  }
+];
+
 // src/registry/server.ts
 function createApp(config, store) {
   const app = new Hono22();
@@ -4431,6 +4987,21 @@ function createApp(config, store) {
     c2.set("config", config);
     await next();
   });
+  const authRouteScopes = config.auth?.mode === "keycloak" ? routeScopes : [];
+  app.use("*", createAuthMiddleware(config, authRouteScopes));
+  app.onError((err, c2) => {
+    if (err instanceof AuthError) {
+      return c2.json(
+        { error: err.code, message: err.message, statusCode: err.statusCode },
+        err.statusCode
+      );
+    }
+    console.error("Unhandled error:", err);
+    return c2.json(
+      { error: "internal_error", message: "Internal server error", statusCode: 500 },
+      500
+    );
+  });
   app.route("/v1/specs", pushRoute);
   app.route("/v1/specs", validateRoute);
   app.route("/v1/specs", listRoute);
@@ -4458,7 +5029,8 @@ function createApp(config, store) {
 // src/registry/config.ts
 var defaultConfig = {
   port: 3750,
-  database: "sqlite"
+  database: "sqlite",
+  auth: { mode: "none" }
 };
 
 // src/registry/storage/sqlite.ts
@@ -5071,17 +5643,63 @@ var provisions2 = pgTable("provisions", {
 // src/registry/storage/postgresql.ts
 import { v4 as uuid6 } from "uuid";
 var MIGRATIONS_FOLDER2 = PG_MIGRATIONS_FOLDER;
+var DatabaseConnectionError = class extends Error {
+  constructor(message, postgresUrl, options) {
+    super(message, options);
+    this.postgresUrl = postgresUrl;
+    this.name = "DatabaseConnectionError";
+  }
+  postgresUrl;
+};
+function isConnectionError(err) {
+  if (typeof err !== "object" || err === null) return false;
+  if ("code" in err) {
+    const code = err.code;
+    if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND") {
+      return true;
+    }
+  }
+  if (err instanceof AggregateError) {
+    if (err.errors.some(isConnectionError)) return true;
+  }
+  if ("cause" in err && err.cause) {
+    return isConnectionError(err.cause);
+  }
+  return false;
+}
+function maskPostgresPassword(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) parsed.password = "***";
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
 var PostgreSQLSpecStore = class {
   db;
   pool;
+  postgresUrl;
   constructor(postgresUrl) {
+    this.postgresUrl = postgresUrl;
     this.pool = new Pool({ connectionString: postgresUrl });
     this.db = drizzle2(this.pool);
   }
   async migrate() {
-    await migrate2(this.db, {
-      migrationsFolder: MIGRATIONS_FOLDER2
-    });
+    try {
+      await migrate2(this.db, {
+        migrationsFolder: MIGRATIONS_FOLDER2
+      });
+    } catch (err) {
+      if (isConnectionError(err)) {
+        throw new DatabaseConnectionError(
+          `PostgreSQL is not reachable at ${maskPostgresPassword(this.postgresUrl)}`,
+          this.postgresUrl,
+          { cause: err }
+        );
+      }
+      throw err;
+    }
   }
   async end() {
     await this.pool.end();
@@ -5511,15 +6129,34 @@ var DEFAULT_REGISTRY_URL = "http://localhost:3750";
 async function startHubServer(userConfig) {
   const config = {
     port: userConfig?.port ?? DEFAULT_PORT,
-    registryUrl: userConfig?.registryUrl ?? DEFAULT_REGISTRY_URL
+    registryUrl: userConfig?.registryUrl ?? DEFAULT_REGISTRY_URL,
+    auth: userConfig?.auth
   };
   const app = new Hono23();
+  app.get("/config.js", (c2) => {
+    const clientConfig = {
+      registryUrl: config.registryUrl,
+      auth: config.auth ? {
+        mode: config.auth.mode,
+        serverUrl: config.auth.serverUrl,
+        realm: config.auth.realm,
+        clientId: config.auth.clientId,
+        audience: config.auth.audience
+      } : void 0
+    };
+    c2.header("Content-Type", "application/javascript");
+    return c2.body(
+      `window.__GRAPITY_CONFIG__ = ${JSON.stringify(clientConfig)};`
+    );
+  });
   app.use("/v1/*", async (c2) => {
     const url = new URL(c2.req.url);
     const targetUrl = config.registryUrl + url.pathname + url.search;
+    const headers = new Headers(c2.req.raw.headers);
+    headers.delete("host");
     const response = await fetch(targetUrl, {
       method: c2.req.method,
-      headers: c2.req.raw.headers,
+      headers,
       body: c2.req.raw.body
     });
     return response;
@@ -5527,13 +6164,21 @@ async function startHubServer(userConfig) {
   app.use("/*", serveStatic({ root: HUB_DIST_PATH }));
   app.get("/*", async (c2) => {
     const indexPath = path10.join(HUB_DIST_PATH, "index.html");
-    if (fs10.existsSync(indexPath)) {
-      return c2.html(fs10.readFileSync(indexPath, "utf-8"));
+    if (!fs10.existsSync(indexPath)) {
+      return c2.text(
+        "index.html not found. Build the project with 'bun run build' first.",
+        404
+      );
     }
-    return c2.text(
-      "index.html not found. Build the project with 'bun run build' first.",
-      404
+    const html = fs10.readFileSync(indexPath, "utf-8");
+    const configScript = `
+    <script src="/config.js"></script>
+  `;
+    const injected = html.replace(
+      "</head>",
+      `${configScript}</head>`
     );
+    return c2.html(injected);
   });
   serve2({
     fetch: app.fetch,
@@ -5545,76 +6190,148 @@ if (process.argv[1] === new URL(import.meta.url).pathname) {
 }
 
 // src/cli/commands/serve.ts
-function getPackageVersion() {
-  try {
-    const pkgPath = new URL("../../../../package.json", import.meta.url);
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version;
-  } catch {
-    return "unknown";
-  }
-}
 function resolveServerConfig(cliOptions, cliConfig) {
+  if (cliConfig.mode === "remote") {
+    throw new Error(
+      `grapity serve is for local mode only. Your config is set to remote (${cliConfig.remote?.url ?? "no URL"}). Use grapity serve on the machine running the local registry.`
+    );
+  }
   const envUrl = process.env.GRAPITY_DATABASE_URL;
-  const dbValue = envUrl ?? cliOptions.db;
-  if (dbValue) {
-    if (isPostgresqlUrl(dbValue)) {
-      return { port: cliOptions.port, database: "postgresql", postgresUrl: dbValue };
-    }
-    return { port: cliOptions.port, database: "sqlite", sqlitePath: dbValue };
+  const local = cliConfig.local;
+  const dbValue = envUrl ?? local?.postgresUrl;
+  const base = { port: cliOptions.port };
+  if (dbValue && isPostgresqlUrl(dbValue)) {
+    base.database = "postgresql";
+    base.postgresUrl = dbValue;
+  } else {
+    base.database = "sqlite";
+    base.sqlitePath = dbValue ?? local?.sqlitePath ?? path11.join(os4.homedir(), ".grapity", "registry.db");
   }
-  if (cliConfig.mode === "local") {
-    const local = cliConfig.local;
-    if (local?.database === "postgresql") {
-      if (!local.postgresUrl) {
-        throw new Error(
-          "PostgreSQL is configured but no postgresUrl is set. Run grapity init --local --db postgresql://... or set GRAPITY_DATABASE_URL."
-        );
-      }
-      return { port: cliOptions.port, database: "postgresql", postgresUrl: local.postgresUrl };
-    }
-    return {
-      port: cliOptions.port,
-      database: "sqlite",
-      sqlitePath: local?.sqlitePath ?? path11.join(os4.homedir(), ".grapity", "registry.db")
-    };
+  if (cliOptions.noAuth) {
+    base.auth = { mode: "none" };
+  } else {
+    base.auth = resolveAuthConfig(local?.auth);
+  }
+  return base;
+}
+function resolveAuthConfig(authConfig) {
+  if (!authConfig || authConfig.mode === "none") {
+    throw new Error(
+      "Authentication is required by default. Configure it with: grapity init --local --auth keycloak ...\nOr run with: grapity serve --no-auth"
+    );
+  }
+  if (!authConfig.serverUrl) {
+    throw new Error(
+      "Keycloak auth is configured but serverUrl is missing. Run grapity init --local --auth keycloak --keycloak-server <url> ..."
+    );
+  }
+  if (!authConfig.realm) {
+    throw new Error(
+      "Keycloak auth is configured but realm is missing. Run grapity init --local --auth keycloak --keycloak-realm <realm> ..."
+    );
   }
   return {
-    port: cliOptions.port,
-    database: "sqlite",
-    sqlitePath: path11.join(os4.homedir(), ".grapity", "registry.db")
+    mode: "keycloak",
+    serverUrl: authConfig.serverUrl.replace(/\/$/, ""),
+    realm: authConfig.realm,
+    audience: authConfig.audience,
+    roleSource: authConfig.roleSource
   };
 }
-function createServeCommand(_version) {
-  return new Command19("serve").description("Start the local grapity registry server").option("-p, --port <port>", "Port to listen on", "3750").option("--hub-port <port>", "Port for the developer portal (Hub)", "3000").option("--no-hub", "Skip starting the developer portal").option("--db <path-or-url>", "SQLite path or postgresql:// URL").action(async (options) => {
+async function verifyKeycloakReachable(serverUrl, realm) {
+  const url = `${serverUrl}/realms/${realm}/.well-known/openid-configuration`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+    if (!res.ok) {
+      throw new Error(`Keycloak returned ${res.status}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Keycloak is not reachable at ${url}: ${message}
+See https://grapity.dev/docs/cli-reference/init#local-mode-with-keycloak to set up a local Keycloak server.
+Or run with: grapity serve --no-auth`
+    );
+  }
+}
+function formatDatabaseConnectionError(err) {
+  return formatError(
+    "PostgreSQL is not reachable",
+    err.message,
+    [
+      "Make sure PostgreSQL is running and accessible.",
+      "Check the database URL in ~/.grapity/config.yaml or GRAPITY_DATABASE_URL."
+    ]
+  );
+}
+function createServeCommand(version2) {
+  return new Command20("serve").description("Start the local grapity registry server").option("-p, --port <port>", "Port to listen on", "3750").option("--hub-port <port>", "Port for the developer portal (Hub)", "3000").option("--no-hub", "Skip starting the developer portal").option("--no-auth", "Start without authentication").action(async (options) => {
     const port = parseInt(options.port, 10);
     const hubPort = parseInt(options.hubPort, 10);
     const startHub = options.hub !== false;
-    const version2 = getPackageVersion();
+    const noAuth = options.auth === false;
+    if (!configExists()) {
+      console.error(
+        formatError(
+          "not initialized",
+          "Run grapity init first to configure the local registry.",
+          ["Example: grapity init --local"]
+        )
+      );
+      process.exit(1);
+    }
     const cliConfig = getConfig();
     let serverConfig;
     try {
-      serverConfig = resolveServerConfig({ port, db: options.db }, cliConfig);
+      serverConfig = resolveServerConfig({ port, noAuth }, cliConfig);
     } catch (err) {
       console.error(formatError("invalid config", err.message));
       process.exit(1);
     }
-    console.log(formatHeader("grapity Registry", `v${version2}`));
+    if (serverConfig.auth?.mode === "keycloak" && !noAuth) {
+      try {
+        await verifyKeycloakReachable(
+          serverConfig.auth.serverUrl,
+          serverConfig.auth.realm
+        );
+      } catch (err) {
+        console.error(formatError("keycloak unreachable", err.message));
+        process.exit(1);
+      }
+    }
+    console.log(formatHeader("grapity", `v${version2}`));
+    console.log("");
+    console.log(formatHeader("grapity Registry"));
     console.log("");
     console.log(
       formatServeConfig({
         port,
         database: serverConfig.database,
         dbPath: serverConfig.sqlitePath,
-        postgresUrl: serverConfig.postgresUrl
+        postgresUrl: serverConfig.postgresUrl,
+        authMode: serverConfig.auth?.mode,
+        keycloakServer: serverConfig.auth?.mode === "keycloak" ? serverConfig.auth.serverUrl : void 0,
+        keycloakRealm: serverConfig.auth?.mode === "keycloak" ? serverConfig.auth.realm : void 0,
+        keycloakAudience: serverConfig.auth?.mode === "keycloak" ? serverConfig.auth.audience : void 0
       })
     );
     console.log("");
-    const { store } = await startServer(serverConfig);
+    let store;
+    try {
+      const started = await startServer(serverConfig);
+      store = started.store;
+    } catch (err) {
+      if (err instanceof DatabaseConnectionError) {
+        console.error(formatDatabaseConnectionError(err));
+      } else {
+        console.error(formatError("failed to start server", err.message));
+      }
+      process.exit(1);
+    }
     console.log(formatReady(port));
     if (startHub) {
       console.log("");
-      console.log(formatHeader("grapity Hub", `v${version2}`));
+      console.log(formatHeader("grapity Hub"));
       console.log("");
       console.log(
         formatHubConfig({
@@ -5625,7 +6342,14 @@ function createServeCommand(_version) {
       console.log("");
       await startHubServer({
         port: hubPort,
-        registryUrl: `http://localhost:${port}`
+        registryUrl: `http://localhost:${port}`,
+        auth: serverConfig.auth?.mode === "keycloak" ? {
+          mode: "keycloak",
+          serverUrl: serverConfig.auth.serverUrl,
+          realm: serverConfig.auth.realm,
+          clientId: "grapity-hub",
+          audience: serverConfig.auth.audience
+        } : void 0
       });
       console.log(formatHubReady(hubPort));
     }
@@ -5644,7 +6368,7 @@ function createServeCommand(_version) {
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../../package.json");
-var program = new Command20();
+var program = new Command21();
 program.name("grapity").description("grapity - API spec registry and compatibility guardian").version(version).addHelpText(
   "after",
   "\nDocumentation: https://grapity.dev/docs/getting-started/quickstart"
@@ -5652,5 +6376,6 @@ program.name("grapity").description("grapity - API spec registry and compatibili
 program.addCommand(registryCommand);
 program.addCommand(gatewayCommand);
 program.addCommand(initCommand);
+program.addCommand(authCommand);
 program.addCommand(createServeCommand(version));
 program.parse();