@njinlabs/njin 0.11.0-beta.1 → 0.11.0

package/README.md

@@ -338,6 +338,21 @@ All `/api/*` endpoints require `Authorization: Bearer <token>`.
 
 njin exposes a remote [MCP](https://modelcontextprotocol.io) server at `POST /mcp` (Streamable HTTP), so an agent such as Claude Cowork or Claude Desktop can read and edit content, change settings and upload files.
 
+**Other AI clients.** Any MCP client that speaks Streamable HTTP and OAuth with dynamic client registration can connect. These OAuth callbacks are accepted out of the box: Claude, ChatGPT, Cursor, VS Code, and any loopback address (`localhost` / `127.0.0.1` — what Gemini CLI, Claude Code, Codex CLI, MCP Inspector and similar desktop clients use). For a client with its own hosted callback, allow it in `config.ts` — and only for clients you trust, since it is where the sign-in code is sent:
+
+```ts
+export default defineConfig({
+  mcp: {
+    redirectUris: [
+      "https://app.example.com/oauth/callback",   // exact
+      "https://client.example.com/connectors/*",  // path prefix
+    ],
+  },
+});
+```
+
+A client that can't do OAuth but can send a header can use a token from `POST /api/mcp-token` instead.
+
 **Connecting Claude:** add a custom connector and enter only the URL, `https://your-site.com/mcp`. Claude opens an njin sign-in page, you log in with your normal njin account and click **Allow** — no token to copy. The site must be reachable from the internet over HTTPS; set `publicUrl` in `config.ts` if it sits behind a proxy that rewrites the host.
 
 | Tool | |
@@ -349,6 +364,8 @@ njin exposes a remote [MCP](https://modelcontextprotocol.io) server at `POST /mc
 | `create_upload_url`, `check_upload` | Add files (below) |
 | `list_files`, `get_file`, `delete_file` | Manage uploaded files |
 
+**Links.** A relation or file field takes the related record's id as a plain string, and that is what `list_models` tells the agent. If an agent sends an object instead (`{ "id": "..." }`, or a whole record read earlier) it is reduced to the id before saving — otherwise njin would store a dead embedded copy rather than a link. Created and updated records come back with their relations expanded, with a `_warnings` entry if a link points at nothing, and reads flag records that already hold an embedded `{ id }` copy so they can be repaired.
+
 **Files.** File bytes can't go through a tool call, so `create_upload_url` returns a short-lived link (10 minutes, up to 10 files of 10 MB). The agent uploads with `curl -F file=@photo.jpg <url>`, or — if it has no shell or network — shows the link so you can open it and drop the file. `check_upload` then returns the file ids to put in a model's file field. Only safe types are accepted (images except SVG, PDF, Office documents, audio, video, zip, fonts); HTML, SVG and scripts are rejected because `/uploads` is served from the site's own origin.
 
 **Managing connections.** Every connected agent is a token you can revoke:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.11.0-beta.1",
+  "version": "0.11.0",
   "description": "A modern framework for building company profiles, landing pages, and content-driven websites.",
   "type": "module",
   "keywords": [

package/src/core/admin_schema.ts

@@ -27,10 +27,35 @@ const stripHiddenFields = (node: any): void => {
 // non-JSON-representable renderAs types (relation/multi_relation/file) into
 // plain JSON-schema shapes the admin panel can render a form from, and drops
 // any field marked hideForm: true so it never reaches the admin panel.
-export const toAdminSchema = (schema: z.ZodObject) => {
+//
+// `forAgent` describes every link (relation/file/multi_*) as what it takes on the wire: the
+// related record's id as a plain string. The admin shape for a single relation is an object
+// `{ id }`, which is right for the panel's form but wrong for an agent: a relation written as an
+// object is stored as an embedded copy instead of a link to the record, so it never expands.
+export const toAdminSchema = (
+  schema: z.ZodObject,
+  options: { forAgent?: boolean } = {},
+) => {
   const jsonSchema = schema.toJSONSchema({
     unrepresentable: "any",
     override: (ctx) => {
+      if (options.forAgent) {
+        const kind = ctx.jsonSchema.renderAs;
+        const target = String(ctx.jsonSchema.model ?? "");
+
+        if (kind === "relation" || kind === "file") {
+          ctx.jsonSchema.type = "string";
+          ctx.jsonSchema.description = `Id of a "${target}" record, as a plain string (not an object).`;
+          return;
+        }
+        if (kind === "multi_relation" || kind === "multi_file") {
+          ctx.jsonSchema.type = "array";
+          ctx.jsonSchema.items = { type: "string" };
+          ctx.jsonSchema.description = `Ids of "${target}" records, as plain strings (not objects).`;
+          return;
+        }
+      }
+
       if (ctx.jsonSchema.renderAs === "relation") {
         ctx.jsonSchema.type = "object";
         ctx.jsonSchema.properties = {

package/src/core/config.ts

@@ -45,6 +45,13 @@ export type NjinConfig = {
   // Optional: falls back to the request's own origin (see core/public_url.ts), which is
   // enough for a single-host setup without a proxy rewriting Host.
   publicUrl?: string;
+  mcp?: {
+    // Extra OAuth callback URLs an MCP client may register, on top of the built-in ones (Claude,
+    // ChatGPT, Cursor, VS Code, and any loopback address). An entry is matched exactly, or as a
+    // path prefix when it ends in "*" ("https://app.example.com/oauth/*"). Only add callbacks of
+    // clients you trust: it is where the authorization code is sent after a user signs in.
+    redirectUris?: string[];
+  };
   // Base directory every project-relative path (src/views, _admin, public, upload dirs)
   // resolves against. Defaults to process.cwd() — only needs overriding by a build step
   // (see build-worker.ts) that bakes in an absolute path for a runtime whose cwd isn't
@@ -78,6 +85,7 @@ export type NjinConfig = {
 export type ResolvedConfig = {
   port: number;
   publicUrl?: string;
+  mcp: { redirectUris: string[] };
   rootDir: string;
   db: {
     path: string;
@@ -149,6 +157,7 @@ export const loadConfig = async (preloaded?: NjinConfig): Promise<void> => {
   resolved = {
     port: userConfig.port ?? 3000,
     publicUrl: userConfig.publicUrl,
+    mcp: { redirectUris: userConfig.mcp?.redirectUris ?? [] },
     rootDir: userConfig.rootDir ?? process.cwd(),
     db: {
       path: userConfig.db?.path ?? "rocksdb://data",

package/src/core/html_page.ts

@@ -45,7 +45,7 @@ label{display:block;font-size:14px;margin:12px 0 4px}
 input[type=email],input[type=password]{width:100%;padding:10px 12px;border:1px solid var(--line);border-radius:8px;background:transparent;color:inherit;font:inherit}
 .row{display:flex;gap:8px;margin-top:20px}
 button{flex:1;padding:10px 12px;border-radius:8px;border:1px solid var(--line);background:transparent;color:inherit;font:inherit;cursor:pointer}
-button.primary{background:var(--accent);color:var(--accent-fg);border-color:var(--accent)}
+button.primary{background:var(--accent);color:var(--accent-fg);border-color:var(--accent);order:1}
 .error{color:var(--danger);font-size:14px;margin:0 0 12px}
 input[type=file]{width:100%;padding:32px 12px;border:2px dashed var(--line);border-radius:8px;background:transparent;color:inherit;font:inherit;cursor:pointer}
 .ok{color:var(--fg)}

package/src/modules/mcp.ts

@@ -21,7 +21,7 @@ const INSTRUCTIONS = `Manage the content of an njin website.
 Start with list_models: it returns every content model and settings (vars) group with its JSON schema. Then use read_records / get_record to look at existing content before changing it.
 
 Field conventions:
-- A relation field takes the id of the related record (a string, not the whole record).
+- A relation or file field takes the id of the related record as a plain string — never an object and never the whole record (an object is stored as a dead copy, not a link). Records you read, create or update come back with their relations expanded one level. A "_warnings" entry means a link points at a record that does not exist, or holds an embedded {id} object instead of a link: fix it with update_record, sending the plain id string.
 - A field with renderAs "file" takes the id of a file record, not a URL.
 - update_record and update_vars only change the fields you send; omitted fields are kept.
 - Validation errors name the offending field — fix it and retry instead of guessing.
@@ -52,6 +52,126 @@ const ok = (data: unknown): ToolResult => ({
 const bareId = (prefix: string, id: string) =>
   id.startsWith(`${prefix}:`) ? id.slice(prefix.length + 1) : id;
 
+const RELATION_KINDS = new Set([
+  "relation",
+  "multi_relation",
+  "file",
+  "multi_file",
+]);
+
+type RelationField = { name: string; many: boolean; target: string };
+
+// A model or a vars group — both carry the zod schema the link fields are read from.
+type HasSchema = { validation: z.ZodObject };
+
+const relationFieldsOf = (model: HasSchema): RelationField[] =>
+  Object.entries(model.validation.shape).flatMap(([name, field]) => {
+    const meta = (field as z.ZodType).meta() as
+      | { renderAs?: string; model?: string }
+      | undefined;
+    if (!RELATION_KINDS.has(meta?.renderAs ?? "")) return [];
+
+    return [
+      {
+        name,
+        many:
+          meta?.renderAs === "multi_relation" ||
+          meta?.renderAs === "multi_file",
+        target: meta?.model ?? "",
+      },
+    ];
+  });
+
+const toLinkId = (target: string, value: unknown) => {
+  const raw =
+    value && typeof value === "object" && "id" in value
+      ? (value as { id: unknown }).id
+      : value;
+
+  return typeof raw === "string" ? bareId(target, raw) : value;
+};
+
+// A relation written as an object (`{ id }`, or a whole record echoed back from a read) is stored
+// by njin as an embedded copy, not a link — it never expands and goes stale. Agents do send that
+// shape, so reduce every link field to the plain id string before validation turns it into a
+// real record link. Also drops a "table:" prefix that doesn't belong in a link.
+const normalizeRelations = (
+  model: HasSchema,
+  data: Record<string, unknown>,
+) => {
+  const next = { ...data };
+
+  for (const { name, many, target } of relationFieldsOf(model)) {
+    const value = next[name];
+    if (value === undefined || value === null) continue;
+
+    next[name] =
+      many && Array.isArray(value)
+        ? value.map((item) => toLinkId(target, item))
+        : toLinkId(target, value);
+  }
+
+  return next;
+};
+
+// An expanded link always carries the target's own fields; a bare `{ id }` is what an embedded
+// stub looks like (a link written as an object before this was normalised).
+//
+// A RecordId (a link that wasn't expanded) has no own enumerable keys, so it must be ruled out
+// first — `[].every(...)` is true and every healthy bare link would be reported as a stub.
+const isStub = (value: unknown) => {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value) || value instanceof RecordId) return false;
+
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => key === "id");
+};
+
+const stubFieldsOf = (model: HasSchema, row: Record<string, unknown>) =>
+  relationFieldsOf(model)
+    .filter(({ name, many }) =>
+      many
+        ? Array.isArray(row[name]) && (row[name] as unknown[]).some(isStub)
+        : isStub(row[name]),
+    )
+    .map(({ name }) => name);
+
+const stubWarning = (field: string, recordId?: string) =>
+  `${recordId ? `Record ${recordId}: ` : ""}"${field}" holds an embedded {id} object, not a link, so it cannot expand. Fix it with update_record, sending "${field}" as the plain id string.`;
+
+// create()/update() hand back the row exactly as stored, so every relation field is a bare id —
+// the agent can't tell a link that resolved from one pointing at nothing (SurrealDB drops a
+// dangling link from a FETCH instead of erroring). Re-read through show(), the same FETCH
+// get_record uses, so related records come back expanded, and flag any link that didn't resolve.
+const readBack = async (model: Model, written: Record<string, unknown>) => {
+  const id =
+    written.id instanceof RecordId ? String(written.id.id) : String(written.id);
+  const shown = ((await model.show(id)) ?? written) as Record<string, unknown>;
+
+  const warnings: string[] = [];
+  for (const { name: field } of relationFieldsOf(model)) {
+    const stored = written[field];
+    if (stored === null || stored === undefined) continue;
+
+    const resolved = shown[field];
+    const isRecord = (value: unknown) => !!value && typeof value === "object";
+    const missing = Array.isArray(stored)
+      ? stored.length -
+        (Array.isArray(resolved) ? resolved.filter(isRecord).length : 0)
+      : isRecord(resolved)
+        ? 0
+        : 1;
+
+    if (missing > 0) {
+      warnings.push(
+        `"${field}": ${missing} linked record(s) do not exist — check the id(s) you sent.`,
+      );
+    }
+  }
+
+  return warnings.length ? { ...shown, _warnings: warnings } : shown;
+};
+
 const fail = (message: string): ToolResult => ({
   content: [{ type: "text", text: message }],
   isError: true,
@@ -96,12 +216,12 @@ const mcp = makeModule(() => {
       models: [...models.values()].map((model) => ({
         name: model.name,
         prefix: model.prefix,
-        schema: toAdminSchema(model.validation),
+        schema: toAdminSchema(model.validation, { forAgent: true }),
       })),
       vars: [...groups.values()].map((group) => ({
         name: group.name,
         prefix: group.prefix,
-        schema: toAdminSchema(group.validation),
+        schema: toAdminSchema(group.validation, { forAgent: true }),
       })),
     };
 
@@ -185,7 +305,30 @@ const mcp = makeModule(() => {
         async ({ model, ...options }) =>
           run(async () => {
             audit("read_records", model);
-            return getModel(model).read(options);
+            // [] means "not specified", same as an empty value over REST — passing it through
+            // would suppress every FETCH and leave relations as bare ids.
+            const populate =
+              Array.isArray(options.populate) && options.populate.length === 0
+                ? undefined
+                : options.populate;
+            const target = getModel(model);
+            const result = await target.read({ ...options, populate });
+
+            const warnings = (result.data as Record<string, unknown>[]).flatMap(
+              (row) =>
+                stubFieldsOf(target, row).map((field) =>
+                  stubWarning(
+                    field,
+                    row.id instanceof RecordId
+                      ? String(row.id.id)
+                      : String(row.id),
+                  ),
+                ),
+            );
+
+            return warnings.length
+              ? { ...result, _warnings: warnings.slice(0, 20) }
+              : result;
           }),
       );
 
@@ -200,9 +343,16 @@ const mcp = makeModule(() => {
         async ({ model, id }) =>
           run(async () => {
             audit("get_record", model, id);
-            const record = await getModel(model).show(bareId(model, id));
+            const target = getModel(model);
+            const record = (await target.show(bareId(model, id))) as
+              | Record<string, unknown>
+              | undefined;
             if (!record) throw new Error(`No ${model} record with id "${id}"`);
-            return record;
+
+            const stubs = stubFieldsOf(target, record);
+            return stubs.length
+              ? { ...record, _warnings: stubs.map((f) => stubWarning(f)) }
+              : record;
           }),
       );
 
@@ -221,7 +371,14 @@ const mcp = makeModule(() => {
           run(async () => {
             audit("create_record", model);
             const target = getModel(model);
-            return target.create(target.validation.parse(data) as never);
+            return readBack(
+              target,
+              (await target.create(
+                target.validation.parse(
+                  normalizeRelations(target, data),
+                ) as never,
+              )) as Record<string, unknown>,
+            );
           }),
       );
 
@@ -242,9 +399,14 @@ const mcp = makeModule(() => {
           run(async () => {
             audit("update_record", model, id);
             const target = getModel(model);
-            return target.update(
-              bareId(model, id),
-              target.validation.partial().parse(data) as never,
+            return readBack(
+              target,
+              (await target.update(
+                bareId(model, id),
+                target.validation
+                  .partial()
+                  .parse(normalizeRelations(target, data)) as never,
+              )) as Record<string, unknown>,
             );
           }),
       );
@@ -269,14 +431,20 @@ const mcp = makeModule(() => {
         {
           title: "Get settings",
           description:
-            "Get the current values of a settings (vars) group, defaults filled in.",
+            "Get the current values of a settings (vars) group, defaults filled in. Relation and file fields come back as ids (use get_record / get_file to look them up).",
           inputSchema: { group: z.string().describe("Group prefix") },
           annotations: { readOnlyHint: true },
         },
         async ({ group }) =>
           run(async () => {
             audit("get_vars", group);
-            return getGroup(group).get();
+            const target = getGroup(group);
+            const values = (await target.get()) as Record<string, unknown>;
+
+            const stubs = stubFieldsOf(target, values);
+            return stubs.length
+              ? { ...values, _warnings: stubs.map((f) => stubWarning(f)) }
+              : values;
           }),
       );
 
@@ -297,7 +465,9 @@ const mcp = makeModule(() => {
             audit("update_vars", group);
             const target = getGroup(group);
             return target.update(
-              target.validation.partial().parse(data) as never,
+              target.validation
+                .partial()
+                .parse(normalizeRelations(target, data)) as never,
             );
           }),
       );

package/src/modules/oauth.ts

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import Elysia from "elysia";
 import moment from "moment";
 import { eq, RecordId, Table } from "surrealdb";
+import { getConfig } from "../core/config";
 import { escapeHtml, noStore, page } from "../core/html_page";
 import { makeModule } from "../core/module";
 import { publicBase } from "../core/public_url";
@@ -25,12 +26,19 @@ const CODE_TTL_MINUTES = 10;
 const UNUSED_CLIENT_TTL_HOURS = 24;
 
 // Dynamic registration is open to anyone who can reach the server, so the redirect URI is the
-// only thing stopping a rogue client from receiving an authorization code — only the hosted
-// Claude callbacks and loopback addresses (native/dev clients, RFC 8252) are accepted.
-const HOSTED_CALLBACKS = new Set([
+// only thing stopping a rogue client from receiving an authorization code. Only these known
+// callbacks, anything in config `mcp.redirectUris`, and loopback addresses (native/dev clients,
+// RFC 8252 — Gemini CLI, VS Code and others use these) are accepted. An entry ending in "*" is a
+// path prefix. Sources: each vendor's own docs (ChatGPT's callback carries a per-connector id).
+const BUILT_IN_REDIRECTS = [
   "https://claude.ai/api/mcp/auth_callback",
   "https://claude.com/api/mcp/auth_callback",
-]);
+  "https://chatgpt.com/connector_platform_oauth_redirect",
+  "https://chatgpt.com/connector/oauth/*",
+  "cursor://anysphere.cursor-mcp/oauth/callback",
+  "https://vscode.dev/redirect",
+  "https://insiders.vscode.dev/redirect",
+];
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
 const parseUrl = (value: string) => {
@@ -41,12 +49,31 @@ const parseUrl = (value: string) => {
   }
 };
 
+// Compares parsed parts, never raw strings: `https://chatgpt.com@evil.com/...` and
+// `https://chatgpt.com.evil.com/...` both start with an allowed string but are other hosts, and
+// `..` segments are already resolved by URL parsing before the path is compared.
+const matchesEntry = (url: URL, entry: string) => {
+  const wildcard = entry.endsWith("*");
+  const base = parseUrl(wildcard ? entry.slice(0, -1) : entry);
+  if (!base) return false;
+
+  if (url.protocol !== base.protocol || url.host !== base.host) return false;
+
+  return wildcard
+    ? url.pathname.startsWith(base.pathname)
+    : url.pathname === base.pathname && url.search === base.search;
+};
+
 const isAllowedRedirectUri = (value: string) => {
   const url = parseUrl(value);
-  if (!url || url.hash) return false;
-  if (HOSTED_CALLBACKS.has(value)) return true;
+  if (!url || url.hash || url.username || url.password) return false;
 
-  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname)) return true;
+
+  const extra = getConfig().mcp?.redirectUris ?? [];
+  return [...BUILT_IN_REDIRECTS, ...extra].some((entry) =>
+    matchesEntry(url, entry),
+  );
 };
 
 // Exact match, except that a loopback client's ephemeral port is ignored (RFC 8252 §7.3) —
@@ -146,8 +173,10 @@ ${hidden("state", params.state)}
 <label for="password">Password</label>
 <input id="password" name="password" type="password" autocomplete="current-password" required>
 <div class="row">
-<button type="submit" name="action" value="deny" formnovalidate>Deny</button>
+<!-- Allow must come first in the markup: pressing Enter in a field submits with the form's
+first submit button, and that must never be Deny. CSS puts Deny back on the left. -->
 <button type="submit" name="action" value="approve" class="primary">Allow</button>
+<button type="submit" name="action" value="deny" formnovalidate>Deny</button>
 </div>
 </form>`,
     status,
@@ -339,7 +368,7 @@ const oauth = makeModule(() => {
           ) {
             return oauthError(
               "invalid_redirect_uri",
-              "redirect_uris must be the Claude callback or a loopback address.",
+              "redirect_uris must be a known client callback or a loopback address (extra callbacks go in config mcp.redirectUris).",
             );
           }