Skip to content

plugin-security

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

plugin-security

README.md

@objectstack/plugin-security

Security plugin for ObjectStack — RBAC, Row-Level Security (RLS), and Field-Level Masking enforced transparently through the ObjectQL middleware chain.

npm License: Apache-2.0

Overview

plugin-security hooks into the ObjectQL pipeline and applies authorization on every read and write:

  1. Resolve permission sets — expand the user's positions and direct grants against SysPermissionSet metadata.
  2. Check object CRUD — allowRead, allowCreate, allowEdit, allowDelete.
  3. Inject RLS — compile row-level policy expressions into query filters.
  4. Mask fields — remove non-readable fields from results; flag non-editable fields on writes.

System-context operations bypass checks so internal jobs, migrations, and seed scripts work unobstructed.

Installation

pnpm add @objectstack/plugin-security

Quick Start

import { ObjectKernel } from '@objectstack/core';
import { SecurityPlugin } from '@objectstack/plugin-security';

const kernel = new ObjectKernel();
kernel.use(new SecurityPlugin());
await kernel.bootstrap();

Multi-tenant vs single-tenant

SecurityPlugin is single-tenant by default. It enforces RBAC, owner-based RLS, and Field-Level Security regardless of mode.

For multi-tenant (logical row-level Organization scoping) the organization wall itself is not in this package and not in this repository. It ships as the enterprise @objectstack/organizations runtime, whose OrganizationsPlugin registers the org-scoping service; a host app declares and installs it in its own package.json, and objectstack serve resolves it from the app rather than from the framework. It must be registered before SecurityPlugin, so the posture probe below finds it.

Asking for the wall without the package is not a silent downgrade: objectstack serve prints FATAL: tenancy posture '<posture>' was requested but @objectstack/organizations could not be loaded and refuses to boot (ADR-0093 D5), unless the operator explicitly sets OS_ALLOW_DEGRADED_TENANCY=1. objectstack doctor reports the same missing runtime.

⚠️ Earlier revisions of this page told readers to install @objectstack/plugin-org-scoping and register an OrgScopingPlugin from it. No such package exists — not on npm, and in no directory of this repo. The open edition ships no organization wall; there is nothing to install here to get one.

SecurityPlugin resolves the tenancy posture (single | group | isolated) once at start time — preferring the tenancy service, and falling back to probing getService('org-scoping') (present ⇒ the historical isolated posture). Two consequences:

  • Tenant isolation is not an RLS policy. Since ADR-0095 D1 the organization wall is Layer 0 (tenant-layer.ts): an independent filter AND-composed ahead of business RLS, so a business-RLS change can never weaken it (W1) and the viewAllRecords / modifyAllRecords superuser bypass can never cross it (W2 — crossing takes a true PLATFORM_ADMIN). Under the single posture Layer 0 is inert. Accordingly the default member_default / viewer_readonly sets ship no wildcard tenant_isolation policy: member_default carries the owner-scoped owner_only_writes / owner_only_deletes plus per-object _self carve-outs on the better-auth identity tables, and viewer_readonly carries the _self carve-outs only.
  • The platform's own tenant-scoped RLS policies are still stripped when no wall is enforced (single), so single-tenant deployments aren't filtered to zero rows and don't pay the field-existence safety net on every find — e.g. organization_admin's sys_member_org / sys_invitation_org / sys_team_org, and the sys_organization_self carve-out. The strip is by provenance, not by pattern-matching the predicate: an app-authored tenant policy is never stripped — it reaches the compiler and fails closed there, with a one-time operator warning (ADR-0105 D3).

organization_id auto-injection on insert is provided by that organizations runtime; owner_id auto-injection always runs in SecurityPlugin regardless.

In CLI / dev-server mode the OS_MULTI_ORG_ENABLED environment variable (default false) toggles whether the runtime registers OrganizationsPlugin alongside SecurityPlugin. Set OS_MULTI_ORG_ENABLED=true before objectstack serve / pnpm dev to enable.

Key Exports

Export Kind Description
SecurityPlugin class Kernel plugin that installs the four-step security chain.
PermissionEvaluator class Evaluates object-level CRUD permissions across the held permission sets (most-permissive merge).
RLSCompiler class Compiles RLS expressions into ObjectQL filter AST.
FieldMasker class Strips non-readable fields and identifies non-editable ones.
SysPosition, SysPermissionSet objects Metadata objects registered by the plugin.

System objects

The plugin contributes these system objects to the kernel:

Object Purpose
sys_position Position (岗位) definitions — the flat permission-set distribution layer (ADR-0090 D3).
sys_permission_set Bundles object and field permissions; can include RLS expressions and a delegated-admin admin_scope (ADR-0090 D12).

Assignment tables (position ↔ user, position ↔ permission_set, user ↔ permission_set) are registered alongside and governed by the delegated-admin and audience-anchor gates.

RLS expression language

RLS policies are authored in the same expression language as object validations. Example:

{
  "object": "project_task",
  "read": "owner_id = $user.id OR team_id in $user.team_ids"
}

Compilation output is a filter AST merged into every query's where clause, so drivers see it as a normal filter.

When to use

  • ✅ Any multi-user deployment.
  • ✅ Enforcing tenant isolation — the wall itself comes from the enterprise organizations runtime described above, not from this package.

When not to use

  • ❌ Trusted single-user CLI scripts — disable per-request via the system context.

Related Packages

Links

License

Apache-2.0. See LICENSING.md.