Access rules API

Exact names, values and behavior of Content Engine access rules. For a guided setup, follow Access rules or Category access. How access is enforced explains where the rules apply.

access optionCopy Anchor Link

Container collectionCopy Anchor Link

defineContentContainer({ access }) from @vitnode/core/content:

defaults is a partial Record<action, { mode: "everyone" } | { mode: "members" }>. Role ids belong to one installation, so roles are chosen only in the AdminCP.

Content filed with a field.container() into the collection, and records under them (container: true relations, thread replies), follow the container's rules.

Content typeCopy Anchor Link

defineContentType({ access }) takes exactly one of:

from must name a shared (not localized) field.relation() whose target has access: { scope }. Anything else throws a ContentEngineError when the plugin loads.

Actions and audiencesCopy Anchor Link

Root roles follow the rules like any other role. An audience of roles lets a root role in only when its id is in roleIds. A rule whose roles were all deleted, or that cannot be read, lets nobody in. Stored rules are per scope and action; an action without one inherits from the nearest ancestor, then the defaults, then everyone.

The constants are exported from @vitnode/core/content: CONTENT_ACCESS_ACTIONS, CONTENT_ACCESS_MODES, CONTENT_ACCESS_PREREQUISITES, CONTENT_ACCESS_MAX_ROLES and CONTENT_ACCESS_REQUIRED_CODE.

createContentAccessCopy Anchor Link

createContentAccess(c) from @vitnode/core/content/server checks the current viewer inside a Hono route. Roles are read from the database once per request; the results are memoized for that request.

import { createContentAccess } from "@vitnode/core/content/server";

const access = createContentAccess(c);
const [row] = await c
  .get("db")
  .select({ id: topics.id, slug: topics.slug })
  .from(topics)
  .where(
    and(
      eq(topics.id, id),
      publicTopic(),
      await access.condition(topicContent, "read"), 
    ),
  )
  .limit(1);

if (!(await access.isOpen(topicContent))) {
  return c.json(row, 200, { "Cache-Control": "private, no-store" });
}

model is the content model from createContentModel. Records of a model without access are always allowed. Put condition in the query before limit and offset, so pages and counts never include what the viewer may not read.

Lower-level helpers are exported from the same path for plugin authors who build their own scope checks: contentAccessCondition, canAccessContentRecord, contentRecordAccessFlags, decideContentAccessForScopes, contentAccessFlagsForScopes, contentAccessRequirementsForScopes, contentRecordAccessScopes, contentAccessAllowedScopes, isContentAccessOpen, resolveContentAccessActor and expireContentAccessFamily.

Response fieldsCopy Anchor Link

Access flagsCopy Anchor Link

interface ContentAccessFlags {
  canView: boolean;
  canRead: boolean;
  canComment: boolean;
  canDownloadAttachments: boolean;
}

• Every record of the public container routes carries access: ContentAccessFlags. Collections without access answer every flag true.
• GET /permissions of a content type adds the four flags to each record it returns, and leaves out records the viewer may not read.

Flags tell the UI what to offer. The server checks again on every request.

Access requiredCopy Anchor Link

A detail route answers 404 when the record is in a scope the viewer may not see, and 403 with this body when the viewer may see the scope but not read it:

{ "accessRequired": true, "code": "CONTENT_ACCESS_REQUIRED" }

The body never holds the record. Render it with ContentAccessRequired from @vitnode/core/tanstack/content:

Guests get a sign-in link that returns to the page. Members get the message only.

Download routeCopy Anchor Link

GET /api/{pluginId}/content/{publicApi.path}/{id}/files/{fileId} is mounted for every content type with access rules. It answers 200 with the file, 403 when the viewer may read the record but not download attachments, and 404 otherwise. See Protected attachments.

AdminCP routesCopy Anchor Link

Mounted under the scope family's admin module, /api/{pluginId}/admin/content/{admin.permissionModule}. For Forum that is /api/@vitnode/forum/admin/content/forum_forums; for Blog categories /api/@vitnode/blog/admin/content/categories.

A content type filed under scopes gets POST /access/effective in its own module, such as /api/@vitnode/blog/admin/content/posts/access/effective. It takes { scopeIds } (up to 50) and answers what readers need for each action across all of them, plus missing scope ids. ContentAccessEffectiveNotice from @vitnode/core/views/admin/views/access/effective-notice renders it in an editor.

overrides is a partial Record<action, audience>. An action left out inherits. Call these routes with rawFetcher:

import { rawFetcher } from "@vitnode/core/tanstack/fetcher";

await rawFetcher({
  method: "put",
  pluginId: "@vitnode/forum",
  prefixPath: "/admin",
  module: "content/forum_forums",
  path: "/3/access",
  body: { overrides: { read: { mode: "roles", roleIds: [4] } } },
});

ErrorsCopy Anchor Link

The routes answer { code, message }:

Activity Logs and eventCopy Anchor Link

Every save that changes a rule records content.access_updated in AdminCP → Staff → Administrators → Logs, in the same transaction as the rules, with the old and new rule of each changed action. Protect public files records content.access_files_protected with the counts it returned. See Activity logs.

PUT /{id}/access also emits content.access.updated after saving:

import { buildEventListener } from "@vitnode/core/api/lib/events";

export const accessListener = buildEventListener({
  event: "content.access.updated",
  name: "log-access-change",
  handler: async (c, { changedActions, family, scopeId, userId }) => {
    await c
      .get("log")
      .debug(`${family}:${scopeId} ${changedActions.join(", ")} by ${userId}`);
  },
});

See Built-in events.

Private storage storeCopy Anchor Link

A storage adapter opts into private files with private on its StorageApiPlugin:

interface StoragePrivateStore {
  upload: (args: StorageUploadArgs) => Promise<{ key: string }>;
  read: (key: string) => Promise<null | { body: ReadableStream<Uint8Array>; size?: number }>;
  delete: (key: string) => Promise<void>;
}

Objects in it have no URL; VitNode serves them only through routes that check the viewer. Leave private out when the adapter cannot guarantee that nothing public reaches it. The Local adapter, and S3 or Supabase with privateBucket, provide one.

RelatedCopy Anchor Link

• How access is enforced
• Protected attachments