@intx/hub-api 0.1.2

package/README.md

@@ -0,0 +1,29 @@
+# @intx/hub-api
+
+Hono application factory for the hub. Owns the public HTTP API
+surface: routes, middleware (session, tenant resolution, grant
+enforcement), authentication via better-auth, and the OpenAPI
+spec served from the running app.
+
+Consumed by `apps/hub` as the HTTP entry point. The factory takes
+the database client, session service, sidecar router, repo store,
+asset service, and event collector registry from `@intx/db` and
+`@intx/hub-sessions` and returns a configured Hono app.
+
+`createApp` returns a configured Hono app. Its `CreateAppOpts`
+parameter wires together the dependencies the API needs: a
+better-auth `authHandler` and matching `getSession`, the database
+client (`db`), the `SidecarRouter` and `SessionService` from
+`@intx/hub-sessions`, and an `EventCollectorRegistry`. The
+`assetService` and `repoStore` fields must be supplied but accept
+`null` for deployments that don't host the git surface; the
+`grantStore` and `sidecarWsHandler` fields are fully optional. See
+`CreateAppOpts` in `src/app.ts` for the exact field list. The
+companion `createAuth` factory builds the better-auth instance
+that supplies `authHandler` and `getSession`.
+
+`createRequireGrant` is the grant-enforcement middleware factory
+exposed for callers that mount additional routes against the same
+authorization stack; it composes with the tenant and session
+middleware so every route sees a resolved principal, tenant, and
+grant decision.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@intx/hub-api",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@hono/standard-validator": "^0.2.2",
+    "@intx/authz": "0.0.0",
+    "@intx/crypto-node": "0.0.0",
+    "@intx/db": "0.0.0",
+    "@intx/hub-common": "0.0.0",
+    "@intx/hub-sessions": "0.0.0",
+    "@intx/log": "0.0.0",
+    "@intx/mime": "0.0.0",
+    "@intx/storage-isogit": "0.0.0",
+    "@intx/types": "0.0.0",
+    "arktype": "^2.1.29",
+    "better-auth": "^1.4.18",
+    "hono": "^4.11.9",
+    "hono-openapi": "^1.2.0"
+  }
+}

package/src/app.test.ts

@@ -0,0 +1,225 @@
+import { describe, test, expect } from "bun:test";
+import { type } from "arktype";
+import { Hono } from "hono";
+import type { DB } from "@intx/db";
+import { createApp, createHubContextMiddleware, mountHubRoutes } from "./app";
+import type { AppEnv } from "./context";
+import {
+  createEventCollectorRegistry,
+  createSidecarRouter,
+  type SessionService,
+} from "@intx/hub-sessions";
+import type { GetSession } from "./session";
+
+const OpenAPISpec = type({
+  info: { title: "string", version: "string" },
+  paths: "Record<string, Record<string, unknown>>",
+});
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- drizzle PgDatabase type cannot be structurally satisfied in tests
+const mockDb = {} as unknown as DB["db"];
+const sidecarRouter = createSidecarRouter({});
+const sessionService: SessionService = {
+  launchSession(_params) {
+    throw new Error("mock: sessionService.launchSession not implemented");
+  },
+  sendUserMessage(_params) {
+    throw new Error("mock: sessionService.sendUserMessage not implemented");
+  },
+  endSession(_addr, _reason) {
+    throw new Error("mock: sessionService.endSession not implemented");
+  },
+};
+const eventCollectors = createEventCollectorRegistry({ db: mockDb });
+
+const app = createApp({
+  getSession: async () => null,
+  authHandler: () => new Response("", { status: 404 }),
+  db: mockDb,
+  sidecarRouter,
+  sessionService,
+  eventCollectors,
+  assetService: null,
+  repoStore: null,
+});
+
+describe("app", () => {
+  test("GET /status returns ok", async () => {
+    const res = await app.request("/status");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ status: "ok" });
+  });
+
+  test("GET /openapi.json returns a valid spec with expected tags", async () => {
+    const res = await app.request("/openapi.json");
+    expect(res.status).toBe(200);
+
+    const spec = OpenAPISpec.assert(await res.json());
+
+    expect(spec.info.title).toBe("Interchange Hub");
+    expect(spec.info.version).toBe("0.0.0");
+
+    const paths = Object.keys(spec.paths);
+    expect(paths.length).toBeGreaterThan(50);
+
+    const tags = new Set<string>();
+    for (const methods of Object.values(spec.paths)) {
+      for (const op of Object.values(methods)) {
+        if (typeof op !== "object" || op === null) continue;
+        if (!("tags" in op)) continue;
+        const { tags: opTags } = op;
+        if (!Array.isArray(opTags)) continue;
+        for (const tag of opTags) {
+          if (typeof tag === "string") tags.add(tag);
+        }
+      }
+    }
+
+    const expectedTags = [
+      "User",
+      "Tenants",
+      "Principals",
+      "Roles",
+      "Grants",
+      "Agents",
+      "Instances",
+      "Approvals",
+      "Wallets",
+      "Credentials",
+      "Discovery",
+      "Observability",
+      "Agent Data",
+      "Sidecars",
+    ];
+
+    for (const tag of expectedTags) {
+      expect(tags.has(tag)).toBe(true);
+    }
+  });
+
+  test("federation routes do not double the /federation path segment", async () => {
+    const res = await app.request("/openapi.json");
+    const spec = OpenAPISpec.assert(await res.json());
+    const federationPaths = Object.keys(spec.paths).filter((p) =>
+      p.includes("federation"),
+    );
+
+    expect(federationPaths.length).toBeGreaterThan(0);
+    for (const p of federationPaths) {
+      expect(p).not.toContain("federation/federation");
+    }
+  });
+
+  test("POST with invalid body returns 400", async () => {
+    const res = await app.request("/api/tenants", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  test("opting out of asset+repo-store hides the git-tokens mint surface", async () => {
+    // Token minting is only useful when at least one smart-HTTP route
+    // consumes the tokens. With `assetService: null` and
+    // `repoStore: null` there is no consumer, so the OpenAPI spec
+    // must not advertise the `Git Tokens` tag and the mint paths
+    // must not appear. The HTTP-request shape would test the same
+    // invariant but is noisier — the auth middleware fronts the
+    // `/api/me/*` tree and short-circuits with 401 before the router
+    // matches, masking whether the route exists.
+    const res = await app.request("/openapi.json");
+    const spec = OpenAPISpec.assert(await res.json());
+
+    const tags = new Set<string>();
+    for (const methods of Object.values(spec.paths)) {
+      for (const op of Object.values(methods)) {
+        if (typeof op !== "object" || op === null) continue;
+        if (!("tags" in op)) continue;
+        const { tags: opTags } = op;
+        if (!Array.isArray(opTags)) continue;
+        for (const tag of opTags) {
+          if (typeof tag === "string") tags.add(tag);
+        }
+      }
+    }
+    expect(tags.has("Git Tokens")).toBe(false);
+
+    const paths = Object.keys(spec.paths);
+    const gitTokenPaths = paths.filter((p) => p.includes("git-tokens"));
+    expect(gitTokenPaths).toEqual([]);
+  });
+});
+
+describe("mountHubRoutes composition", () => {
+  const stubUser = {
+    id: "usr_compose",
+    email: "compose@example.com",
+    emailVerified: true,
+    name: "Compose Test",
+    image: null,
+    createdAt: new Date("2025-01-01"),
+    updatedAt: new Date("2025-01-01"),
+  };
+  const stubSession = {
+    id: "ses_compose",
+    userId: stubUser.id,
+    token: "tok_compose",
+    expiresAt: new Date("2999-01-01"),
+    createdAt: stubUser.createdAt,
+    updatedAt: stubUser.updatedAt,
+  };
+  const getSession: GetSession = async () => ({
+    user: stubUser,
+    session: stubSession,
+  });
+
+  test("third-party Hono app shares the hub's request context", async () => {
+    const thirdParty = new Hono<AppEnv>();
+    thirdParty.use(createHubContextMiddleware({ getSession }));
+
+    // A sibling route owned by the third party reads from the same
+    // request context the hub routes use.
+    thirdParty.get("/sibling/whoami", (c) => {
+      const user = c.get("user");
+      return c.json({ userId: user?.id ?? null });
+    });
+
+    mountHubRoutes(thirdParty, {
+      db: mockDb,
+      sidecarRouter,
+      sessionService,
+      eventCollectors,
+      assetService: null,
+      repoStore: null,
+    });
+
+    const siblingRes = await thirdParty.request("/sibling/whoami");
+    expect(siblingRes.status).toBe(200);
+    expect(await siblingRes.json()).toEqual({ userId: stubUser.id });
+
+    // Hub routes mounted on the same app respond as expected.
+    const statusRes = await thirdParty.request("/status");
+    expect(statusRes.status).toBe(200);
+    expect(await statusRes.json()).toEqual({ status: "ok" });
+  });
+
+  test("mountHubRoutes does not mount an auth handler at /api/auth/*", async () => {
+    const thirdParty = new Hono<AppEnv>();
+    thirdParty.use(createHubContextMiddleware({ getSession }));
+    mountHubRoutes(thirdParty, {
+      db: mockDb,
+      sidecarRouter,
+      sessionService,
+      eventCollectors,
+      assetService: null,
+      repoStore: null,
+    });
+
+    // Without an auth handler mounted by the caller, /api/auth/* is
+    // free for the third party to wire as they choose.
+    const res = await thirdParty.request("/api/auth/anything");
+    expect(res.status).toBe(404);
+  });
+});

package/src/app.ts

@@ -0,0 +1,382 @@
+import type { Handler, MiddlewareHandler } from "hono";
+import { Hono } from "hono";
+import { openAPIRouteHandler } from "hono-openapi";
+
+import { honoLogger, type HonoContext } from "@intx/log/hono";
+import { timeWindowEvaluator } from "@intx/authz";
+import { type DB, createGrantStore } from "@intx/db";
+import type { ConditionRegistry, GrantStore } from "@intx/types/authz";
+
+import type { AppEnv } from "./context";
+import { createSessionMiddleware } from "./middleware/session";
+import { createRequireGrant, type RequireGrant } from "./middleware/grant";
+import { createResolveTenant, requireAuth } from "./middleware/tenant";
+import type { GetSession } from "./session";
+import type {
+  AssetService,
+  EventCollectorRegistry,
+  RepoStore,
+  SessionService,
+  SidecarRouter,
+} from "@intx/hub-sessions";
+
+import { createMeRoutes } from "./routes/me";
+import { createTenantRoutes } from "./routes/tenants";
+import { createTenantFederationRoutes } from "./routes/tenant-federation";
+import { createPrincipalRoutes, createInviteRoutes } from "./routes/principals";
+import { createRoleRoutes, createRoleAssignRoutes } from "./routes/roles";
+import { createGrantRoutes, createEvaluateRoutes } from "./routes/grants";
+import { createAgentRoutes } from "./routes/agents";
+import { createInstanceRoutes } from "./routes/instances";
+import { createApprovalRoutes } from "./routes/approvals";
+import { createWalletRoutes } from "./routes/wallets";
+import { createProviderRoutes } from "./routes/providers";
+import { createOAuthClientRoutes } from "./routes/oauth-clients";
+import { createCredentialRoutes } from "./routes/credentials";
+import { createOfferingRoutes, createModelRoutes } from "./routes/offerings";
+import { createObservabilityRoutes } from "./routes/observability";
+import { createAgentDataRoutes } from "./routes/agent-data";
+import { createSidecarRoutes } from "./routes/sidecars";
+import {
+  createMeGitTokenRoutes,
+  createTenantGitTokenRoutes,
+} from "./routes/git-tokens";
+import {
+  ASSET_OPENAPI_EXCLUDE_GLOBS,
+  createAssetRoutes,
+} from "./routes/assets";
+import {
+  AGENT_STATE_OPENAPI_EXCLUDE_GLOBS,
+  createAgentStateDefinitionGitRoutes,
+  createAgentStateInstanceGitRoutes,
+  createAgentStateReceivePackDeny,
+} from "./routes/agent-state-git";
+import { createGitTokenAuth } from "./middleware/git-token-auth";
+
+export type CreateHubContextMiddlewareDeps = {
+  getSession: GetSession;
+};
+
+/**
+ * Builds the per-request context middleware that resolves the
+ * authenticated user and session from the incoming request and
+ * exposes them via the Hono variable bag.
+ */
+export function createHubContextMiddleware({
+  getSession,
+}: CreateHubContextMiddlewareDeps): MiddlewareHandler<AppEnv> {
+  return createSessionMiddleware(getSession);
+}
+
+export type MountHubRoutesDeps = {
+  db: DB["db"];
+  sidecarRouter: SidecarRouter;
+  sessionService: SessionService;
+  eventCollectors: EventCollectorRegistry;
+  grantStore?: GrantStore;
+  conditionRegistry?: ConditionRegistry;
+  sidecarWsHandler?: Handler<AppEnv>;
+  /**
+   * The asset REST endpoint and smart-HTTP route group mount under
+   * `/api/tenants/:tenantId/assets` when both are supplied. Tests
+   * that have no reason to exercise the asset surface MUST pass
+   * `null` for both to opt out explicitly; passing only one is a
+   * wiring bug and throws at construction.
+   */
+  assetService: AssetService | null;
+  repoStore: RepoStore | null;
+};
+
+/**
+ * Mounts every hub route group, middleware, and supporting endpoint
+ * onto the provided Hono application. The caller is responsible for
+ * having mounted the request logger and the context middleware first,
+ * and for wiring their own auth handler at the path of their choice.
+ *
+ * `grantStore` and `conditionRegistry` default to the hub's standard
+ * choices (a database-backed grant store and the time-window condition
+ * evaluator) when not supplied.
+ */
+export function mountHubRoutes(
+  app: Hono<AppEnv>,
+  opts: MountHubRoutesDeps,
+): void {
+  const {
+    db,
+    sidecarRouter,
+    sessionService,
+    eventCollectors,
+    sidecarWsHandler,
+    assetService,
+    repoStore,
+  } = opts;
+  if ((assetService === null) !== (repoStore === null)) {
+    throw new Error(
+      "mountHubRoutes: assetService and repoStore must be provided together or both omitted",
+    );
+  }
+  const grantStore = opts.grantStore ?? createGrantStore(db);
+  const conditionRegistry: ConditionRegistry = opts.conditionRegistry ?? {
+    time_window: timeWindowEvaluator,
+  };
+  const requireGrant: RequireGrant = createRequireGrant({
+    grantStore,
+    conditionRegistry,
+  });
+  const resolveTenant = createResolveTenant({ db });
+
+  app.get("/status", (c) => c.json({ status: "ok" }));
+
+  // User-scoped (cross-tenant) -- requires auth but not tenant membership
+  app.use("/api/me/*", requireAuth);
+  app.route("/api/me", createMeRoutes({ db }));
+
+  // The git-tokens mint surface mounts under the same gate as the
+  // smart-HTTP route groups: tokens are only useful when at least one
+  // smart-HTTP route consumes them. Both deps null = no smart-HTTP
+  // anywhere = no token-mint endpoints.
+  if (repoStore !== null) {
+    app.route("/api/me/git-tokens", createMeGitTokenRoutes({ db }));
+  }
+
+  // Smart-HTTP asset routes use bearer authentication instead of
+  // session+tenant resolution. The bearer middleware mounts ahead of
+  // resolveTenant so it populates `principal` + `tenant` first; the
+  // tenant resolver short-circuits when both are already set, which
+  // lets bearer-only requests bypass the session-required path.
+  //
+  // The gate is `repoStore !== null` rather than the two-dep check;
+  // the XOR throw above already guarantees the deps move as a unit,
+  // so checking either one is equivalent. Keeping a single shape
+  // across every gate site makes the contract obvious to a reader.
+  if (repoStore !== null) {
+    app.use(
+      "/api/tenants/:tenantId/assets/:kind/:nameDotGit/*",
+      createGitTokenAuth({ db }),
+    );
+  }
+
+  // Agent-state smart-HTTP read routes also use bearer auth. The
+  // receive-pack denial middleware mounts BEFORE bearer auth so an
+  // unauthenticated `git push -v` parses the pkt-line ERR record
+  // rather than a generic 401. The bearer middleware then gates the
+  // upload-pack half (advertise + POST) on a valid token.
+  if (repoStore !== null) {
+    app.use(
+      "/api/tenants/:tenantId/agents/instances/:instanceId/state.git/*",
+      createAgentStateReceivePackDeny(),
+    );
+    app.use(
+      "/api/tenants/:tenantId/agents/definitions/:agentId/state.git/*",
+      createAgentStateReceivePackDeny(),
+    );
+    app.use(
+      "/api/tenants/:tenantId/agents/instances/:instanceId/state.git/*",
+      createGitTokenAuth({ db }),
+    );
+    app.use(
+      "/api/tenants/:tenantId/agents/definitions/:agentId/state.git/*",
+      createGitTokenAuth({ db }),
+    );
+  }
+
+  // Tenant-scoped middleware -- require auth + tenant membership for any
+  // path under /api/tenants/:tenantId/*. Must be registered before routes
+  // so Hono includes it in the middleware chain.
+  app.use("/api/tenants/:tenantId/*", resolveTenant);
+
+  // Global tenant routes (create needs auth, detail/update handle auth inline)
+  app.route("/api/tenants", createTenantRoutes({ db }));
+  app.route("/api/models", createModelRoutes());
+
+  // Tenant-scoped routes
+  app.route(
+    "/api/tenants/:tenantId/principals",
+    createPrincipalRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/members/invite",
+    createInviteRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/roles",
+    createRoleRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/principals/:principalId/roles",
+    createRoleAssignRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/grants",
+    createGrantRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/principals/:principalId/evaluate",
+    createEvaluateRoutes({ db, grantStore, conditionRegistry }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/agents/definitions",
+    createAgentRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/agents/instances",
+    createInstanceRoutes({
+      db,
+      sessionService,
+      sidecarRouter,
+      eventCollectors,
+      grantStore,
+      conditionRegistry,
+      requireGrant,
+    }),
+  );
+
+  app.route("/api/tenants/:tenantId/approvals", createApprovalRoutes());
+  app.route(
+    "/api/tenants/:tenantId/wallets",
+    createWalletRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/providers",
+    createProviderRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/oauth-clients",
+    createOAuthClientRoutes({ db, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/credentials",
+    createCredentialRoutes({ db, sidecarRouter, requireGrant }),
+  );
+  app.route(
+    "/api/tenants/:tenantId/offerings",
+    createOfferingRoutes({ db, requireGrant }),
+  );
+  if (repoStore !== null) {
+    app.route(
+      "/api/tenants/:tenantId/git-tokens",
+      createTenantGitTokenRoutes({ db, requireGrant }),
+    );
+  }
+  app.route("/api/tenants/:tenantId", createObservabilityRoutes());
+  app.route(
+    "/api/tenants/:tenantId/federation",
+    createTenantFederationRoutes({ db }),
+  );
+  app.route("/api/tenants/:tenantId/agents/:agentId", createAgentDataRoutes());
+
+  if (assetService !== null && repoStore !== null) {
+    app.route(
+      "/api/tenants/:tenantId/assets",
+      createAssetRoutes({
+        db,
+        assetService,
+        repoStore,
+        grantStore,
+        conditionRegistry,
+        requireGrant,
+      }),
+    );
+  }
+
+  if (repoStore !== null) {
+    app.route(
+      "/api/tenants/:tenantId/agents/instances",
+      createAgentStateInstanceGitRoutes({
+        db,
+        repoStore,
+        grantStore,
+        conditionRegistry,
+      }),
+    );
+    app.route(
+      "/api/tenants/:tenantId/agents/definitions",
+      createAgentStateDefinitionGitRoutes({
+        db,
+        repoStore,
+        grantStore,
+        conditionRegistry,
+      }),
+    );
+  }
+
+  app.route(
+    "/api/sidecars",
+    createSidecarRoutes(
+      sidecarWsHandler ? { db, wsHandler: sidecarWsHandler } : { db },
+    ),
+  );
+}
+
+export type CreateAppOpts = {
+  getSession: GetSession;
+  authHandler: Handler<AppEnv>;
+  db: DB["db"];
+  sidecarRouter: SidecarRouter;
+  sessionService: SessionService;
+  eventCollectors: EventCollectorRegistry;
+  grantStore?: GrantStore;
+  sidecarWsHandler?: Handler<AppEnv>;
+  assetService: AssetService | null;
+  repoStore: RepoStore | null;
+};
+
+export function createApp({
+  getSession,
+  authHandler,
+  db,
+  sidecarRouter,
+  sessionService,
+  eventCollectors,
+  grantStore,
+  sidecarWsHandler,
+  assetService,
+  repoStore,
+}: CreateAppOpts) {
+  const app = new Hono<AppEnv>();
+
+  app.use(
+    honoLogger({
+      category: ["hub", "requests"],
+      skip: (c: HonoContext) => c.req.path === "/status",
+    }),
+  );
+
+  app.use(createHubContextMiddleware({ getSession }));
+
+  app.all("/api/auth/*", authHandler);
+
+  mountHubRoutes(app, {
+    db,
+    sidecarRouter,
+    sessionService,
+    eventCollectors,
+    assetService,
+    repoStore,
+    ...(grantStore ? { grantStore } : {}),
+    ...(sidecarWsHandler ? { sidecarWsHandler } : {}),
+  });
+
+  app.get(
+    "/openapi.json",
+    openAPIRouteHandler(app, {
+      documentation: {
+        info: {
+          title: "Interchange Hub",
+          version: "0.0.0",
+        },
+      },
+      exclude: [
+        "/openapi.json",
+        "/status",
+        "/api/auth/**",
+        ...ASSET_OPENAPI_EXCLUDE_GLOBS,
+        ...AGENT_STATE_OPENAPI_EXCLUDE_GLOBS,
+      ],
+    }),
+  );
+
+  return app;
+}
+
+export type App = ReturnType<typeof createApp>;

package/src/auth.ts

@@ -0,0 +1,21 @@
+import type { DB } from "@intx/db";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+
+export function createAuth(db: DB["db"]) {
+  return betterAuth({
+    baseURL: process.env["BETTER_AUTH_BASE_URL"] ?? "http://localhost:3000",
+    database: drizzleAdapter(db, { provider: "pg" }),
+    emailAndPassword: {
+      enabled: true,
+    },
+    socialProviders: {
+      google: {
+        clientId: process.env["GOOGLE_CLIENT_ID"] ?? "",
+        clientSecret: process.env["GOOGLE_CLIENT_SECRET"] ?? "",
+      },
+    },
+  });
+}
+
+export type Auth = ReturnType<typeof createAuth>;