@objectstack/plugin-org-scoping 7.0.0

package/LICENSE

@@ -0,0 +1,93 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             ObjectStack AI LLC
+Licensed Work:        ObjectStack Runtime: the BSL-licensed packages
+                      of the ObjectStack monorepo as listed in LICENSING.md.
+                      Copyright (c) 2026 ObjectStack AI LLC.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to third
+                      parties on a hosted or embedded basis in order to compete with 
+                      ObjectStack AI LLC's paid version(s) of the Licensed Work. For purposes 
+                      of this license:
+
+                      A "competitive offering" is a Product that is offered to third
+                      parties on a paid basis, including through paid support 
+                      arrangements, that significantly overlaps with the capabilities 
+                      of ObjectStack AI LLC's paid version(s) of the Licensed Work. If Your 
+                      Product is not a competitive offering when You first make it 
+                      generally available, it will not become a competitive offering
+                      later due to ObjectStack AI LLC releasing a new version of the Licensed 
+                      Work with additional capabilities. In addition, Products that 
+                      are not provided on a paid basis are not competitive.
+
+                      "Product" means software that is offered to end users to manage 
+                      in their own environments or offered as a service on a hosted 
+                      basis.
+
+                      "Embedded" means including the source code or executable code 
+                      from the Licensed Work in a competitive offering. "Embedded" 
+                      also means packaging the competitive offering in such a way 
+                      that the Licensed Work must be accessed or downloaded for the 
+                      competitive offering to operate.
+
+                      Hosting or using the Licensed Work(s) for internal purposes 
+                      within an organization is not considered a competitive 
+                      offering. ObjectStack AI LLC considers your organization to include all 
+                      of your affiliates under common control.
+
+                      For binding interpretive guidance on using ObjectStack AI LLC products 
+                      under the Business Source License, please visit our FAQ. 
+                      (see LICENSING.md in this repository)
+Change Date:          Four years from the date the Licensed Work is published.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@objectstack.dev.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,55 @@
+# @objectstack/plugin-org-scoping
+
+> Row-level **Organization** isolation for ObjectStack — the LOGICAL multi-tenant building block.
+
+`@objectstack/plugin-org-scoping` makes `sys_organization` a first-class row-level scope:
+
+- **Insert auto-stamp** — fills `organization_id` from `ExecutionContext.tenantId` on every authenticated insert (when the target object declares the column).
+- **Per-org seed replay** — every `sys_organization` insert triggers a copy of the app's demo dataset into the new org (via `seed-replayer`, or fallback `claimOrphanOrgRows` / `cloneOrgSeedData`).
+- **Default-org bootstrap** — the first platform admin gets a `Default Organization` (slug `default`) bound as `owner` on `kernel:ready`, so the dashboard isn't empty after first sign-up.
+
+Pair with [`@objectstack/plugin-security`](../plugin-security/README.md) for full multi-tenant RBAC + RLS + Field-Level Security. Standalone install gives a single-tenant deployment.
+
+## Naming
+
+The word "tenant" in ObjectStack means **physical** isolation (one Environment = one database, per ADR-0002 and `@objectstack/driver-turso`'s multi-tenant router). This plugin is about **logical** row-level scoping inside a single database — orthogonal to physical tenancy. Hence "org-scoping", not "multi-tenant".
+
+## Install
+
+```bash
+pnpm add @objectstack/plugin-org-scoping @objectstack/plugin-security
+```
+
+## Usage
+
+```ts
+import { OrgScopingPlugin } from '@objectstack/plugin-org-scoping';
+import { SecurityPlugin } from '@objectstack/plugin-security';
+
+// OrgScopingPlugin MUST be registered BEFORE SecurityPlugin — the
+// latter probes `getService('org-scoping')` at start time to decide
+// whether to keep wildcard `current_user.organization_id` RLS policies.
+await kernel.use(new OrgScopingPlugin());
+await kernel.use(new SecurityPlugin());
+```
+
+Or via the `OS_MULTI_TENANT` env switch when using `@objectstack/runtime` / `@objectstack/plugin-dev`:
+
+```bash
+OS_MULTI_TENANT=true objectstack serve
+```
+
+## Options
+
+```ts
+new OrgScopingPlugin({
+  ensureDefaultOrganization: true, // default — auto-create slug="default" for first admin
+});
+```
+
+Set `ensureDefaultOrganization: false` to fully self-manage onboarding via invitations / a custom UI.
+
+## See also
+
+- ADR-0002 — Physical multi-tenancy & driver-turso router
+- `@objectstack/plugin-security` — RBAC, RLS, Field-Level Security

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+
+interface OrgScopingPluginOptions {
+    /**
+     * Whether to auto-create a `Default Organization` (slug `default`)
+     * and bind the first platform admin as `owner` when they have zero
+     * memberships. Set to `false` for deployments that fully self-manage
+     * org provisioning via invitation links or a custom onboarding flow.
+     *
+     * @default true
+     */
+    ensureDefaultOrganization?: boolean;
+}
+/**
+ * OrgScopingPlugin
+ *
+ * Makes `sys_organization` a first-class row-level isolation boundary:
+ *
+ *   1. **insert auto-stamp** — on every authenticated `insert` whose
+ *      target object declares `organization_id`, fill the column from
+ *      `ExecutionContext.tenantId`. Without this, freshly-created
+ *      rows have `organization_id = NULL` and the default
+ *      `tenant_isolation` RLS policy hides them from the very user
+ *      who just created them.
+ *
+ *   2. **per-org seed replay** — after `sys_organization` insert, copy
+ *      the artifact's demo seed data into the new org. Three paths
+ *      (in order of preference):
+ *        a. replay registered `seed-datasets` via the kernel-level
+ *           `seed-replayer` callable (set by AppPlugin),
+ *        b. for the FIRST org, `claimOrphanOrgRows` adopts any
+ *           NULL-org rows a previous inline-seed may have inserted,
+ *        c. for SUBSEQUENT orgs, `cloneOrgSeedData` shallow-clones
+ *           rows from the very first org (donor-pattern).
+ *
+ *   3. **default-org bootstrap** — on `kernel:ready` and after every
+ *      `sys_user_permission_set` insert, ensure the platform admin has
+ *      a Default Organization to operate in (idempotent on slug
+ *      `default` + admin's existing memberships).
+ *
+ * Why split from plugin-security:
+ *   - plugin-security is a single-tenant-aware RBAC + RLS engine; it
+ *     should not know about Organization-specific seed flows.
+ *   - This plugin is purely opt-in: not installing it gives a
+ *     single-tenant deployment (no `organization_id` injection, no
+ *     per-org seed clone, no default-org bootstrap). plugin-security
+ *     detects its presence via `getService('org-scoping')` and adjusts
+ *     RLS policy stripping accordingly.
+ *
+ * Naming note: "org-scoping" deliberately avoids the word "tenant"
+ * because in ObjectStack "tenant" already means *physical isolation*
+ * (one Environment = one database, per ADR-0002 and driver-turso's
+ * multi-tenant router). This plugin is about LOGICAL row-level
+ * scoping inside a single database — orthogonal to physical tenancy.
+ *
+ * Dependencies:
+ *   - `objectql` (engine middleware host)
+ */
+declare class OrgScopingPlugin implements Plugin {
+    name: string;
+    type: string;
+    version: string;
+    dependencies: string[];
+    /** Per-object field-name cache; same shape as SecurityPlugin's. */
+    private readonly fieldNamesCache;
+    private readonly opts;
+    constructor(options?: OrgScopingPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+    /**
+     * Resolve the column-name set for an object (mirrors SecurityPlugin's
+     * loader so the two plugins behave consistently). Returns `null` if
+     * the schema can't be loaded — caller skips injection.
+     */
+    private getObjectFieldNames;
+    private loadObjectFieldNames;
+}
+
+interface ClaimOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+/**
+ * Assign every orphaned seed row to `organizationId`.
+ *
+ * Walks `ql.registry.getAllObjects()`, filters to schemas that
+ *   (a) are not `managedBy` (skip sys_/auth/platform tables),
+ *   (b) declare an `organization_id` field,
+ * and runs an `update(where: { organization_id: null }, patch: {
+ * organization_id: organizationId })` against each as `isSystem`.
+ *
+ * Returns a per-object summary `{ object, count }[]`.
+ */
+declare function claimOrphanOrgRows(ql: any, organizationId: string, options?: ClaimOptions): Promise<{
+    object: string;
+    count: number;
+}[]>;
+
+interface CloneOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+declare function cloneOrgSeedData(ql: any, targetOrgId: string, options?: CloneOptions): Promise<{
+    object: string;
+    count: number;
+}[]>;
+
+/**
+ * ensureDefaultOrganization — multi-tenant bootstrap helper.
+ *
+ * In multi-tenant deployments the freshly-promoted platform admin
+ * (`admin_full_access` granted with `organization_id IS NULL`) needs
+ * at least one `sys_organization` to carry an `activeOrganizationId`
+ * on their session. Without it, the default `tenant_isolation` RLS
+ * policy filters everything to zero rows and the admin sees an empty
+ * console even though they have full access.
+ *
+ * Strategy (idempotent, run on `kernel:ready` and after every
+ * `sys_user_permission_set` insert):
+ *
+ *   1. Find the platform admin (oldest `sys_user_permission_set` row
+ *      with `permission_set_id = admin_full_access` and
+ *      `organization_id IS NULL`). If none, no-op.
+ *   2. If that user already has any `sys_member` row, no-op (they
+ *      either created their own org or were invited into one — we
+ *      respect that and never auto-create a "Default Organization"
+ *      behind their back).
+ *   3. Re-use a pre-existing `slug='default'` org if present;
+ *      otherwise create one. Stable slug keeps human-readable URLs
+ *      predictable across cold-boots.
+ *   4. Insert a `sys_member { role: 'owner' }` linking the admin to
+ *      the default org.
+ *
+ * This is the ONLY framework-side auto-provisioning of an org.
+ * Subsequent users must accept an invitation or explicitly create
+ * their first organization — `claimOrphanOrgRows` / `cloneOrgSeedData`
+ * handle the seed-data side for those flows.
+ */
+interface EnsureOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+interface EnsureDefaultOrganizationResult {
+    /** Whether a brand-new org row was inserted (vs. re-using slug=default). */
+    defaultOrgCreated: boolean;
+    /** Resolved (or freshly minted) default-org id; undefined when no admin exists yet. */
+    defaultOrgId?: string;
+    /** Whether a sys_member row was inserted binding the admin to the default org. */
+    memberCreated: boolean;
+    /** Human-readable reason when the helper short-circuited. */
+    reason?: 'no_admin' | 'admin_already_in_org' | 'org_insert_failed' | 'member_insert_failed';
+}
+/**
+ * Ensure the platform admin has a Default Organization to operate in.
+ * Safe to call multiple times — idempotent on stable slug `default`
+ * and on the presence of any existing `sys_member` row for the admin.
+ */
+declare function ensureDefaultOrganization(ql: any, options?: EnsureOptions): Promise<EnsureDefaultOrganizationResult>;
+
+/**
+ * Canonical plugin-org-scoping manifest source.
+ *
+ * Imported by `objectstack.config.ts` (compile-time) and
+ * `org-scoping-plugin.ts` (runtime `manifest.register`) so the two
+ * registration paths cannot drift.
+ */
+declare const ORG_SCOPING_PLUGIN_ID = "com.objectstack.plugin-org-scoping";
+declare const ORG_SCOPING_PLUGIN_VERSION = "1.0.0";
+/** This plugin owns no `sys_*` objects — Organization itself lives in `@objectstack/platform-objects`. */
+declare const orgScopingObjects: readonly [];
+/** Manifest header shared by compile-time config and runtime registration. */
+declare const orgScopingPluginManifestHeader: {
+    id: string;
+    namespace: string;
+    version: string;
+    type: "plugin";
+    scope: "system";
+    defaultDatasource: string;
+    name: string;
+    description: string;
+};
+
+export { type EnsureDefaultOrganizationResult, ORG_SCOPING_PLUGIN_ID, ORG_SCOPING_PLUGIN_VERSION, OrgScopingPlugin, type OrgScopingPluginOptions, claimOrphanOrgRows, cloneOrgSeedData, ensureDefaultOrganization, orgScopingObjects, orgScopingPluginManifestHeader };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+
+interface OrgScopingPluginOptions {
+    /**
+     * Whether to auto-create a `Default Organization` (slug `default`)
+     * and bind the first platform admin as `owner` when they have zero
+     * memberships. Set to `false` for deployments that fully self-manage
+     * org provisioning via invitation links or a custom onboarding flow.
+     *
+     * @default true
+     */
+    ensureDefaultOrganization?: boolean;
+}
+/**
+ * OrgScopingPlugin
+ *
+ * Makes `sys_organization` a first-class row-level isolation boundary:
+ *
+ *   1. **insert auto-stamp** — on every authenticated `insert` whose
+ *      target object declares `organization_id`, fill the column from
+ *      `ExecutionContext.tenantId`. Without this, freshly-created
+ *      rows have `organization_id = NULL` and the default
+ *      `tenant_isolation` RLS policy hides them from the very user
+ *      who just created them.
+ *
+ *   2. **per-org seed replay** — after `sys_organization` insert, copy
+ *      the artifact's demo seed data into the new org. Three paths
+ *      (in order of preference):
+ *        a. replay registered `seed-datasets` via the kernel-level
+ *           `seed-replayer` callable (set by AppPlugin),
+ *        b. for the FIRST org, `claimOrphanOrgRows` adopts any
+ *           NULL-org rows a previous inline-seed may have inserted,
+ *        c. for SUBSEQUENT orgs, `cloneOrgSeedData` shallow-clones
+ *           rows from the very first org (donor-pattern).
+ *
+ *   3. **default-org bootstrap** — on `kernel:ready` and after every
+ *      `sys_user_permission_set` insert, ensure the platform admin has
+ *      a Default Organization to operate in (idempotent on slug
+ *      `default` + admin's existing memberships).
+ *
+ * Why split from plugin-security:
+ *   - plugin-security is a single-tenant-aware RBAC + RLS engine; it
+ *     should not know about Organization-specific seed flows.
+ *   - This plugin is purely opt-in: not installing it gives a
+ *     single-tenant deployment (no `organization_id` injection, no
+ *     per-org seed clone, no default-org bootstrap). plugin-security
+ *     detects its presence via `getService('org-scoping')` and adjusts
+ *     RLS policy stripping accordingly.
+ *
+ * Naming note: "org-scoping" deliberately avoids the word "tenant"
+ * because in ObjectStack "tenant" already means *physical isolation*
+ * (one Environment = one database, per ADR-0002 and driver-turso's
+ * multi-tenant router). This plugin is about LOGICAL row-level
+ * scoping inside a single database — orthogonal to physical tenancy.
+ *
+ * Dependencies:
+ *   - `objectql` (engine middleware host)
+ */
+declare class OrgScopingPlugin implements Plugin {
+    name: string;
+    type: string;
+    version: string;
+    dependencies: string[];
+    /** Per-object field-name cache; same shape as SecurityPlugin's. */
+    private readonly fieldNamesCache;
+    private readonly opts;
+    constructor(options?: OrgScopingPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+    /**
+     * Resolve the column-name set for an object (mirrors SecurityPlugin's
+     * loader so the two plugins behave consistently). Returns `null` if
+     * the schema can't be loaded — caller skips injection.
+     */
+    private getObjectFieldNames;
+    private loadObjectFieldNames;
+}
+
+interface ClaimOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+/**
+ * Assign every orphaned seed row to `organizationId`.
+ *
+ * Walks `ql.registry.getAllObjects()`, filters to schemas that
+ *   (a) are not `managedBy` (skip sys_/auth/platform tables),
+ *   (b) declare an `organization_id` field,
+ * and runs an `update(where: { organization_id: null }, patch: {
+ * organization_id: organizationId })` against each as `isSystem`.
+ *
+ * Returns a per-object summary `{ object, count }[]`.
+ */
+declare function claimOrphanOrgRows(ql: any, organizationId: string, options?: ClaimOptions): Promise<{
+    object: string;
+    count: number;
+}[]>;
+
+interface CloneOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+declare function cloneOrgSeedData(ql: any, targetOrgId: string, options?: CloneOptions): Promise<{
+    object: string;
+    count: number;
+}[]>;
+
+/**
+ * ensureDefaultOrganization — multi-tenant bootstrap helper.
+ *
+ * In multi-tenant deployments the freshly-promoted platform admin
+ * (`admin_full_access` granted with `organization_id IS NULL`) needs
+ * at least one `sys_organization` to carry an `activeOrganizationId`
+ * on their session. Without it, the default `tenant_isolation` RLS
+ * policy filters everything to zero rows and the admin sees an empty
+ * console even though they have full access.
+ *
+ * Strategy (idempotent, run on `kernel:ready` and after every
+ * `sys_user_permission_set` insert):
+ *
+ *   1. Find the platform admin (oldest `sys_user_permission_set` row
+ *      with `permission_set_id = admin_full_access` and
+ *      `organization_id IS NULL`). If none, no-op.
+ *   2. If that user already has any `sys_member` row, no-op (they
+ *      either created their own org or were invited into one — we
+ *      respect that and never auto-create a "Default Organization"
+ *      behind their back).
+ *   3. Re-use a pre-existing `slug='default'` org if present;
+ *      otherwise create one. Stable slug keeps human-readable URLs
+ *      predictable across cold-boots.
+ *   4. Insert a `sys_member { role: 'owner' }` linking the admin to
+ *      the default org.
+ *
+ * This is the ONLY framework-side auto-provisioning of an org.
+ * Subsequent users must accept an invitation or explicitly create
+ * their first organization — `claimOrphanOrgRows` / `cloneOrgSeedData`
+ * handle the seed-data side for those flows.
+ */
+interface EnsureOptions {
+    logger?: {
+        info: (message: string, meta?: Record<string, any>) => void;
+        warn: (message: string, meta?: Record<string, any>) => void;
+    };
+}
+interface EnsureDefaultOrganizationResult {
+    /** Whether a brand-new org row was inserted (vs. re-using slug=default). */
+    defaultOrgCreated: boolean;
+    /** Resolved (or freshly minted) default-org id; undefined when no admin exists yet. */
+    defaultOrgId?: string;
+    /** Whether a sys_member row was inserted binding the admin to the default org. */
+    memberCreated: boolean;
+    /** Human-readable reason when the helper short-circuited. */
+    reason?: 'no_admin' | 'admin_already_in_org' | 'org_insert_failed' | 'member_insert_failed';
+}
+/**
+ * Ensure the platform admin has a Default Organization to operate in.
+ * Safe to call multiple times — idempotent on stable slug `default`
+ * and on the presence of any existing `sys_member` row for the admin.
+ */
+declare function ensureDefaultOrganization(ql: any, options?: EnsureOptions): Promise<EnsureDefaultOrganizationResult>;
+
+/**
+ * Canonical plugin-org-scoping manifest source.
+ *
+ * Imported by `objectstack.config.ts` (compile-time) and
+ * `org-scoping-plugin.ts` (runtime `manifest.register`) so the two
+ * registration paths cannot drift.
+ */
+declare const ORG_SCOPING_PLUGIN_ID = "com.objectstack.plugin-org-scoping";
+declare const ORG_SCOPING_PLUGIN_VERSION = "1.0.0";
+/** This plugin owns no `sys_*` objects — Organization itself lives in `@objectstack/platform-objects`. */
+declare const orgScopingObjects: readonly [];
+/** Manifest header shared by compile-time config and runtime registration. */
+declare const orgScopingPluginManifestHeader: {
+    id: string;
+    namespace: string;
+    version: string;
+    type: "plugin";
+    scope: "system";
+    defaultDatasource: string;
+    name: string;
+    description: string;
+};
+
+export { type EnsureDefaultOrganizationResult, ORG_SCOPING_PLUGIN_ID, ORG_SCOPING_PLUGIN_VERSION, OrgScopingPlugin, type OrgScopingPluginOptions, claimOrphanOrgRows, cloneOrgSeedData, ensureDefaultOrganization, orgScopingObjects, orgScopingPluginManifestHeader };