rastack 0.0.51 → 0.0.52

package/dist/compile/analyze.js

@@ -85,7 +85,9 @@ function analyzeDsl(program, fileNames) {
         });
     }
     // Deterministic order: app, then model.
-    resources.sort((a, b) => a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app));
+    resources.sort((a, b) => a.app === b.app
+        ? a.model.localeCompare(b.model)
+        : a.app.localeCompare(b.app));
     types.sort((a, b) => a.key.localeCompare(b.key));
     return { resources, types };
 }
@@ -116,7 +118,10 @@ function analyzeResourceCall(call, checker) {
     const app = stringLiteralArg(call.arguments[0]);
     const model = stringLiteralArg(call.arguments[1]);
     const fieldsArg = call.arguments[2];
-    if (!app || !model || !fieldsArg || !ts.isObjectLiteralExpression(fieldsArg)) {
+    if (!app ||
+        !model ||
+        !fieldsArg ||
+        !ts.isObjectLiteralExpression(fieldsArg)) {
         return undefined;
     }
     const fields = [];

package/dist/compile/entities.js

@@ -107,8 +107,9 @@ function analyzeEntities(program, fileNames) {
     for (const decl of candidates) {
         if (jsdocTags(decl).has("rastackresource"))
             addRoot(decl);
-        else if (ts.isClassDeclaration(decl) && isDataClass(decl))
+        else if (ts.isClassDeclaration(decl) && isDataClass(decl, checker)) {
             addRoot(decl);
+        }
     }
     // 2. Transitive closure over FK references: an entity's entity-typed
     //    property pulls the referenced declaration in as an entity too.
@@ -131,7 +132,9 @@ function analyzeEntities(program, fileNames) {
         seen.add(decl);
         included.push(decl);
         for (const prop of analyzed(decl)) {
-            if (prop.target && candidates.has(prop.target) && !seen.has(prop.target)) {
+            if (prop.target &&
+                candidates.has(prop.target) &&
+                !seen.has(prop.target)) {
                 queue.push(prop.target);
             }
         }
@@ -152,9 +155,14 @@ function analyzeEntities(program, fileNames) {
         });
         const fields = [];
         const relations = [];
+        let ownerField;
+        let groupField;
         for (const prop of analyzed(decl)) {
             if (prop.skip) {
-                diagnostics.push({ severity: "warning", message: `${key}.${prop.name}: ${prop.skip}` });
+                diagnostics.push({
+                    severity: "warning",
+                    message: `${key}.${prop.name}: ${prop.skip}`,
+                });
                 continue;
             }
             if (prop.inverse)
@@ -179,15 +187,57 @@ function analyzeEntities(program, fileNames) {
             }
             else if (prop.field) {
                 fields.push(prop.field);
+                if (prop.owner) {
+                    if (ownerField) {
+                        diagnostics.push({
+                            severity: "warning",
+                            message: `${key}: multiple Owner fields — keeping "${ownerField}", ignoring "${prop.name}".`,
+                        });
+                    }
+                    else {
+                        ownerField = prop.name;
+                    }
+                }
+                if (prop.group) {
+                    if (groupField) {
+                        diagnostics.push({
+                            severity: "warning",
+                            message: `${key}: multiple Group fields — keeping "${groupField}", ignoring "${prop.name}".`,
+                        });
+                    }
+                    else {
+                        groupField = prop.name;
+                    }
+                }
             }
         }
+        const policy = entityPolicy(decl, checker, naming);
+        let scope = policy.scope;
+        if (!scope && groupField)
+            scope = "group"; // group datasets partition physically by default
+        if (scope === "group" && !groupField) {
+            diagnostics.push({
+                severity: "warning",
+                message: `${key}: GroupScoped without a Group field — add a \`string & Group\` property so rows can be placed in a partition.`,
+            });
+        }
+        const access = {};
+        if (ownerField)
+            access.ownerField = ownerField;
+        if (groupField)
+            access.groupField = groupField;
+        if (scope)
+            access.scope = scope;
+        if (policy.adminGroups?.length)
+            access.adminGroups = policy.adminGroups;
         const resource = {
             app: naming.app,
             model: naming.model,
             fields,
             relations,
             search: naming.search,
-            permission: naming.permission,
+            permission: policy.permission,
+            access: Object.keys(access).length ? access : undefined,
         };
         // A class may declare its state machine inline: `static transitions =
         // {...}`. Statics are never columns, so the block rides alongside the
@@ -195,7 +245,9 @@ function analyzeEntities(program, fileNames) {
         (0, analyze_1.applyTransitions)(resource, staticTransitions(decl));
         resources.push(resource);
     }
-    resources.sort((a, b) => a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app));
+    resources.sort((a, b) => a.app === b.app
+        ? a.model.localeCompare(b.model)
+        : a.app.localeCompare(b.app));
     return { resources, diagnostics, types };
 }
 /**
@@ -263,14 +315,23 @@ function entityBehindType(type, scanned) {
 /**
  * A *plain data class* — the class-authored equivalent of a `resource()` call,
  * so it roots itself. It must carry no heritage clause (a subclass of
- * `React.Component` or a service base is app code, not a table), not be
- * abstract, contain nothing but property declarations, and have at least one
- * instance property. Anything richer can still opt in via a hook or the
+ * `React.Component` or a service base is app code, not a table) — with one
+ * exception: `implements` clauses made **only of auth markers**
+ * (`IsAuthenticated`, `AdminGroups<…>`, `OwnerScoped`, …) are policy, not
+ * behaviour, and keep the class a plain data class. It must not be abstract,
+ * contain nothing but property declarations, and have at least one instance
+ * property. Anything richer can still opt in via a hook or the
  * `@rastackResource` tag.
  */
-function isDataClass(decl) {
-    if (decl.heritageClauses?.length)
-        return false;
+function isDataClass(decl, checker) {
+    for (const clause of decl.heritageClauses ?? []) {
+        if (clause.token !== ts.SyntaxKind.ImplementsKeyword)
+            return false;
+        for (const typeNode of clause.types) {
+            if (!isAccessMarker(checker.getTypeFromTypeNode(typeNode)))
+                return false;
+        }
+    }
     if (ts.getCombinedModifierFlags(decl) &
         (ts.ModifierFlags.Abstract | ts.ModifierFlags.Ambient)) {
         return false;
@@ -337,7 +398,8 @@ function analyzeProperty(name, member, checker, scanned) {
     let typeNode = unwrapParens(member.type);
     if (ts.isUnionTypeNode(typeNode)) {
         const arms = typeNode.types.filter((t) => {
-            const isNullish = (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword) ||
+            const isNullish = (ts.isLiteralTypeNode(t) &&
+                t.literal.kind === ts.SyntaxKind.NullKeyword) ||
                 t.kind === ts.SyntaxKind.UndefinedKeyword;
             if (isNullish)
                 nullable = true;
@@ -449,7 +511,12 @@ function scalarProp(name, base, config, nullable) {
         field.null = true;
     if (config.default !== undefined)
         field.default = config.default;
-    return { name, nullable, field };
+    const info = { name, nullable, field };
+    if (config.owner)
+        info.owner = true;
+    if (config.group)
+        info.group = true;
+    return info;
 }
 /**
  * Config carried in the type system: intersecting a property type with
@@ -479,6 +546,10 @@ function configFromType(type, checker, location) {
         config.unique = true;
     if (prop("primaryKey"))
         config.primaryKey = true;
+    if (prop("owner"))
+        config.owner = true;
+    if (prop("group"))
+        config.group = true;
     const maxLength = prop("maxLength");
     if (maxLength?.isNumberLiteral())
         config.maxLength = maxLength.value;
@@ -501,6 +572,10 @@ function configFromTags(tags) {
         config.unique = true;
     if (tags.has("primarykey"))
         config.primaryKey = true;
+    if (tags.has("owner"))
+        config.owner = true;
+    if (tags.has("group"))
+        config.group = true;
     const maxLength = Number(tags.get("maxlength"));
     if (Number.isFinite(maxLength) && maxLength > 0)
         config.maxLength = maxLength;
@@ -543,7 +618,8 @@ function arrayElement(node) {
         return node.elementType;
     if (ts.isTypeReferenceNode(node) &&
         ts.isIdentifier(node.typeName) &&
-        (node.typeName.text === "Array" || node.typeName.text === "ReadonlyArray") &&
+        (node.typeName.text === "Array" ||
+            node.typeName.text === "ReadonlyArray") &&
         node.typeArguments?.length === 1) {
         return node.typeArguments[0];
     }
@@ -556,7 +632,8 @@ function entityNaming(decl) {
     // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
     // so hook usage of generated types resolves to the same resource.
     const stripped = /^I[A-Z]/.test(raw) ? raw.slice(1) : raw;
-    const model = tags.get("rastackmodel") || stripped.charAt(0).toLowerCase() + stripped.slice(1);
+    const model = tags.get("rastackmodel") ||
+        stripped.charAt(0).toLowerCase() + stripped.slice(1);
     const app = tags.get("rastackapp") ||
         path
             .basename(decl.getSourceFile().fileName)
@@ -565,7 +642,10 @@ function entityNaming(decl) {
     const naming = { app, model };
     const search = tags.get("rastacksearch");
     if (search)
-        naming.search = search.split(",").map((s) => s.trim()).filter(Boolean);
+        naming.search = search
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
     const permission = tags.get("rastackpermission");
     if (permission === "authenticatedOrReadOnly" ||
         permission === "authenticated" ||
@@ -574,6 +654,73 @@ function entityNaming(decl) {
     }
     return naming;
 }
+// -- access policy (auth as types) ---------------------------------------------
+/** The phantom keys the `rastack/auth` entity markers carry. */
+const MARKER_PROPS = [
+    "__rastackPermission",
+    "__rastackAdminGroups",
+    "__rastackScope",
+];
+/** Whether a heritage type is an auth marker (policy, not behaviour). */
+function isAccessMarker(type) {
+    return MARKER_PROPS.some((p) => type.getProperty(p));
+}
+/**
+ * Read the entity's access policy: the auth markers on its heritage clauses
+ * (`implements IsAuthenticated, AdminGroups<"staff">` on a class, `extends`
+ * on an interface) merged over the JSDoc tag equivalents
+ * (`@rastackPermission`, `@rastackAdminGroups`, `@rastackScope`) — the type
+ * wins when both are present, like the `DbConfig` brands do for columns.
+ */
+function entityPolicy(decl, checker, naming) {
+    const policy = {};
+    const tags = jsdocTags(decl);
+    const adminGroupsTag = tags.get("rastackadmingroups");
+    if (adminGroupsTag) {
+        const groups = adminGroupsTag
+            .split(",")
+            .map((g) => g.trim())
+            .filter(Boolean);
+        if (groups.length)
+            policy.adminGroups = groups;
+    }
+    const scopeTag = tags.get("rastackscope");
+    if (scopeTag === "owner" || scopeTag === "group" || scopeTag === "shared") {
+        policy.scope = scopeTag;
+    }
+    policy.permission = naming.permission; // @rastackPermission, parsed with naming
+    for (const clause of decl.heritageClauses ?? []) {
+        for (const typeNode of clause.types) {
+            const type = checker.getTypeFromTypeNode(typeNode);
+            const literals = (prop) => {
+                const symbol = type.getProperty(prop);
+                if (!symbol)
+                    return [];
+                const carrier = checker
+                    .getTypeOfSymbolAtLocation(symbol, decl)
+                    .getNonNullableType();
+                const arms = carrier.isUnion() ? carrier.types : [carrier];
+                return arms
+                    .filter((t) => t.isStringLiteral())
+                    .map((t) => t.value);
+            };
+            const [permission] = literals("__rastackPermission");
+            if (permission === "authenticated" ||
+                permission === "authenticatedOrReadOnly" ||
+                permission === "public") {
+                policy.permission = permission;
+            }
+            const adminGroups = literals("__rastackAdminGroups");
+            if (adminGroups.length)
+                policy.adminGroups = adminGroups.sort();
+            const [scope] = literals("__rastackScope");
+            if (scope === "owner" || scope === "group" || scope === "shared") {
+                policy.scope = scope;
+            }
+        }
+    }
+    return policy;
+}
 /** All JSDoc tags on a node, keyed by lower-cased tag name → comment text. */
 function jsdocTags(node) {
     const tags = new Map();

package/dist/compile/model.d.ts

@@ -46,12 +46,16 @@ export interface AdminModel {
 /**
  * Row-level access control, enforced by `rastack-api-core` on every surface.
  * `ownerField` names the field stamped with the authenticated subject;
- * `scope: "owner"` places the table under a per-identity warehouse prefix
- * (`tenants/{sub}/…`) so object-storage IAM can fence data per user.
+ * `groupField` names the field holding the owning group (rows visible to its
+ * members). `scope: "owner"` places the table under a per-identity warehouse
+ * prefix (`tenants/{sub}/…`) so object-storage IAM can fence data per user;
+ * `scope: "group"` partitions per group (`groups/{name}/…`) so each group's
+ * records are physically stored apart.
  */
 export interface AccessModel {
     ownerField?: string;
-    scope?: "owner" | "shared";
+    groupField?: string;
+    scope?: "owner" | "group" | "shared";
     adminGroups?: string[];
 }
 /**

package/dist/compile/openapi.js

@@ -225,19 +225,29 @@ function syncStamp(operation, resource, verb) {
     return operation;
 }
 /**
- * Stamp `x-rastack-access` on an operation of an access-controlled resource so
- * downstream tooling (hooks, the local cache) knows the owner field and whether
- * the table is tenant-partitioned on object storage.
+ * Stamp `x-rastack-permission` / `x-rastack-access` on an operation so
+ * downstream tooling knows the resource's full access policy: the permission
+ * gate, the owner field (row-level security), tenant scope (the local cache
+ * partitions per identity), and the RLS-bypassing admin groups — everything
+ * `rastack/auth`'s `policyFromOpenApi` needs to mirror the server's rules in
+ * the UI.
  */
 function accessStamp(operation, resource) {
+    if (resource.permission) {
+        operation["x-rastack-permission"] = resource.permission;
+    }
     const access = resource.access;
     if (!access)
         return;
     const stamp = {};
     if (access.ownerField)
         stamp.ownerField = access.ownerField;
+    if (access.groupField)
+        stamp.groupField = access.groupField;
     if (access.scope)
         stamp.scope = access.scope;
+    if (access.adminGroups?.length)
+        stamp.adminGroups = access.adminGroups;
     if (Object.keys(stamp).length)
         operation["x-rastack-access"] = stamp;
 }

package/dist/compile/program.d.ts

@@ -2,7 +2,8 @@ import * as ts from "typescript";
 /**
  * Build a `ts.Program` (and thus a `TypeChecker`) over a set of resource
  * definition files. The authoring subpaths (`rastack/define` for the DSL,
- * `rastack/types` for the `DbConfig` column brands) are mapped to the
+ * `rastack/db` for the `DbConfig` column brands, `rastack/auth` for the auth
+ * markers, `rastack/types` as the alias for both) are mapped to the
  * in-tree/installed sources via `paths` so both the shipped package name and
  * the local demo/tests resolve without extra linking.
  */

package/dist/compile/program.js

@@ -40,7 +40,8 @@ const ts = __importStar(require("typescript"));
 /**
  * Build a `ts.Program` (and thus a `TypeChecker`) over a set of resource
  * definition files. The authoring subpaths (`rastack/define` for the DSL,
- * `rastack/types` for the `DbConfig` column brands) are mapped to the
+ * `rastack/db` for the `DbConfig` column brands, `rastack/auth` for the auth
+ * markers, `rastack/types` as the alias for both) are mapped to the
  * in-tree/installed sources via `paths` so both the shipped package name and
  * the local demo/tests resolve without extra linking.
  */
@@ -61,7 +62,11 @@ function createProgram(fileNames) {
         paths: {
             "rastack/define": [defineDir],
             "rastack/define/*": [defineDir + "/*"],
-            "rastack/types": [path.join(defineDir, "db")],
+            // `rastack/db` = column brands, `rastack/auth` = auth markers + the
+            // Owner/Group brands; `rastack/types` is the compatibility alias for both.
+            "rastack/db": [path.join(defineDir, "db")],
+            "rastack/auth": [path.join(defineDir, "auth")],
+            "rastack/types": [path.join(defineDir, "types")],
         },
     };
     return ts.createProgram(fileNames, options);

package/dist/define/auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `rastack/auth` *authoring* surface — auth as TypeScript types.
+ *
+ * Everything needed to declare an entity's access policy in the type system:
+ * the entity-level markers (`IsAuthenticated`, `AdminGroups<…>`,
+ * `OwnerScoped`, …) and the access-control field brands (`Owner`, `Group`).
+ * The compiler maps the `rastack/auth` import specifier here (see
+ * `compile/program.ts`); the published package additionally exposes the
+ * client runtime (`RastackAuth`, `can`, the React context) under the same
+ * subpath from `tools/auth/`.
+ *
+ * ```ts
+ * import { AdminGroups, Group, IsAuthenticated, Owner, OwnerScoped } from "rastack/auth";
+ *
+ * export class Trip implements IsAuthenticated, AdminGroups<"staff">, OwnerScoped {
+ *   owner!: string & Owner;
+ *   destination!: string;
+ * }
+ *
+ * export class Report implements IsAuthenticated, AdminGroups<"staff"> {
+ *   team!: string & Group;   // group-owned — physically partitioned per group
+ *   title!: string;
+ * }
+ * ```
+ */
+export * from "./markers";
+export type { Owner, Group } from "./db";

package/dist/define/auth.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * The `rastack/auth` *authoring* surface — auth as TypeScript types.
+ *
+ * Everything needed to declare an entity's access policy in the type system:
+ * the entity-level markers (`IsAuthenticated`, `AdminGroups<…>`,
+ * `OwnerScoped`, …) and the access-control field brands (`Owner`, `Group`).
+ * The compiler maps the `rastack/auth` import specifier here (see
+ * `compile/program.ts`); the published package additionally exposes the
+ * client runtime (`RastackAuth`, `can`, the React context) under the same
+ * subpath from `tools/auth/`.
+ *
+ * ```ts
+ * import { AdminGroups, Group, IsAuthenticated, Owner, OwnerScoped } from "rastack/auth";
+ *
+ * export class Trip implements IsAuthenticated, AdminGroups<"staff">, OwnerScoped {
+ *   owner!: string & Owner;
+ *   destination!: string;
+ * }
+ *
+ * export class Report implements IsAuthenticated, AdminGroups<"staff"> {
+ *   team!: string & Group;   // group-owned — physically partitioned per group
+ *   title!: string;
+ * }
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./markers"), exports);

package/dist/define/db.d.ts

@@ -7,7 +7,7 @@
  * off the type — the same way it reads foreign keys.
  *
  * ```ts
- * import { Default, Int, MaxLength, PrimaryKey, Unique, UUID } from "rastack/types";
+ * import { Default, Int, MaxLength, PrimaryKey, Unique, UUID } from "rastack/db";
  *
  * export interface Passenger {
  *   id: UUID & PrimaryKey;
@@ -59,6 +59,29 @@ export interface Default<V extends string | number | boolean> extends DbConfig<{
     default: V;
 }> {
 }
+/**
+ * Marks the column that records the owning identity (the verified token
+ * `sub`): `owner: string & Owner`. Compiles to `access.ownerField` — the row
+ * is stamped from the token on create, immutable after, and rows are only
+ * visible to their owner (plus `AdminGroups` members). Add the `OwnerScoped`
+ * entity marker to *also* partition the table physically per identity.
+ */
+export interface Owner extends DbConfig<{
+    owner: true;
+}> {
+}
+/**
+ * Marks the column that records the owning group (a verified `cognito:groups`
+ * value): `team: string & Group`. Compiles to `access.groupField` — rows are
+ * only visible to members of their group, and the dataset is **physically
+ * partitioned per group** by default (`groups/{name}/…` on object storage),
+ * so each group's records live in their own files. Add the `SharedStorage`
+ * entity marker to keep group rows in one shared table instead.
+ */
+export interface Group extends DbConfig<{
+    group: true;
+}> {
+}
 /** An integer column — a bare `number` property maps to `float`. */
 export type Int = number & DbConfig<{
     int: true;

package/dist/define/db.js

@@ -8,7 +8,7 @@
  * off the type — the same way it reads foreign keys.
  *
  * ```ts
- * import { Default, Int, MaxLength, PrimaryKey, Unique, UUID } from "rastack/types";
+ * import { Default, Int, MaxLength, PrimaryKey, Unique, UUID } from "rastack/db";
  *
  * export interface Passenger {
  *   id: UUID & PrimaryKey;

package/dist/define/index.d.ts

@@ -124,17 +124,34 @@ export interface SyncOptions {
  * - `ownerField` — the field that records the owning identity (the verified
  *   token `sub`). Rows are only listed/read/written by their owner; the field
  *   is stamped from the token on create and immutable on update.
+ * - `groupField` — the field that records the owning *group* (a verified
+ *   `cognito:groups` value). Rows are only visible to members of their group,
+ *   and the dataset defaults to per-group physical partitioning.
  * - `scope: "owner"` — additionally *physically* partitions the resource's
  *   Iceberg table per identity (`tenants/{sub}/{app}.db/{model}/…`), so
  *   object-storage credentials (e.g. Cognito Identity Pool temp creds) can be
  *   IAM-restricted to `tenants/${"${cognito-identity.amazonaws.com:sub}"}/*`.
+ *   `scope: "group"` partitions per group instead (`groups/{name}/…`);
+ *   `scope: "shared"` keeps one table.
  * - `adminGroups` — token groups (`cognito:groups`) that bypass row filters.
+ *
+ * Class/interface entities express the same policy in the type system — the
+ * `Owner`/`Group` field brands and `IsAuthenticated`/`AdminGroups<…>`/
+ * `OwnerScoped` markers from `rastack/auth`.
  */
 export interface AccessOptions {
     ownerField?: string;
-    scope?: "owner" | "shared";
+    groupField?: string;
+    scope?: "owner" | "group" | "shared";
     adminGroups?: string[];
 }
+/**
+ * The resource-level permission gate — which paths an identity may hit at all.
+ * Enforced by `rastack-api-core` before any row is read; mirrored client-side
+ * by `rastack/auth`'s `can()` so components hide what the server would reject.
+ * Unset means `authenticated` — secure by default.
+ */
+export type Permission = "authenticatedOrReadOnly" | "authenticated" | "public";
 /**
  * One edge of a resource's state machine. `from` is the state (or states) the
  * transition may fire from, `to` the state it enters, and `set` the effect —
@@ -193,7 +210,7 @@ export interface ResourceOptions {
     /** Local-first replication config. */
     sync?: SyncOptions;
     /** Access policy (secure by default). */
-    permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
+    permission?: Permission;
     /** Row-level security + physical tenant partitioning. */
     access?: AccessOptions;
     /** Declarative state machine over one field, enforced on every write surface. */

package/dist/define/manifest.js

@@ -230,9 +230,18 @@ function normaliseAccess(access) {
     const model = {};
     if (typeof access.ownerField === "string")
         model.ownerField = access.ownerField;
-    if (access.scope === "owner" || access.scope === "shared") {
+    if (typeof access.groupField === "string")
+        model.groupField = access.groupField;
+    if (access.scope === "owner" ||
+        access.scope === "group" ||
+        access.scope === "shared") {
         model.scope = access.scope;
     }
+    else if (model.groupField) {
+        // Group-owned datasets are physically partitioned per group by default —
+        // that is their point. `scope: "shared"` opts out explicitly.
+        model.scope = "group";
+    }
     if (Array.isArray(access.adminGroups)) {
         model.adminGroups = access.adminGroups.filter((g) => typeof g === "string");
     }

package/dist/define/markers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Entity-level authorization markers — auth as *TypeScript types*.
+ *
+ * Class and interface entities have no options bag, so their access policy is
+ * expressed the same way their columns are: in the type system. Attach a
+ * marker with `implements` (classes) or `extends` (interfaces) and the
+ * compiler reads the policy straight off the heritage clause:
+ *
+ * ```ts
+ * import { AdminGroups, IsAuthenticated, Owner, Group } from "rastack/auth";
+ *
+ * // Per-user rows: RLS on `owner`, staff sees everything.
+ * export class Itinerary implements IsAuthenticated, AdminGroups<"staff"> {
+ *   owner!: string & Owner;
+ *   notes!: string;
+ * }
+ *
+ * // Group-owned dataset: rows belong to a team and are *physically stored*
+ * // under that team's own storage prefix (groups/{team}/…).
+ * export class Report implements IsAuthenticated, AdminGroups<"staff"> {
+ *   team!: string & Group;
+ *   title!: string;
+ * }
+ * ```
+ *
+ * The markers are phantom types: every property is optional and never exists
+ * at runtime, so `implements` needs no members and instances stay plain data.
+ * Each marker family uses its own phantom key, so markers combine freely —
+ * while two *permission* markers on one entity conflict in the type checker,
+ * which is exactly right.
+ *
+ * JSDoc equivalents exist for every marker (`@rastackPermission`,
+ * `@rastackAdminGroups staff, ops`, `@rastackScope owner|group|shared`, and
+ * field-level `@owner` / `@group`), mirroring the column-constraint tags.
+ */
+/** The permission gate carried in the type system. */
+export interface PermissionOf<P extends string> {
+    readonly __rastackPermission?: P;
+}
+/** Every path requires a verified identity (this is also the default). */
+export interface IsAuthenticated extends PermissionOf<"authenticated"> {
+}
+/** Anonymous callers may read (list/retrieve); writes require identity. */
+export interface IsAuthenticatedOrReadOnly extends PermissionOf<"authenticatedOrReadOnly"> {
+}
+/** No gate — every caller may read and write. Opt-in, never the default. */
+export interface IsPublic extends PermissionOf<"public"> {
+}
+/**
+ * Token groups (`cognito:groups`) that bypass row-level security on this
+ * entity — the "is admin" role, driven from scopes: `implements
+ * AdminGroups<"staff" | "ops">`. Members see and act on every row.
+ */
+export interface AdminGroups<G extends string> {
+    readonly __rastackAdminGroups?: G;
+}
+/** Storage scope carried in the type system. */
+export interface ScopeOf<S extends string> {
+    readonly __rastackScope?: S;
+}
+/**
+ * Physically partition the entity's table per identity
+ * (`tenants/{sub}/…`) — the prefix object-storage IAM can fence per user.
+ * Combine with an `Owner` field brand.
+ */
+export interface OwnerScoped extends ScopeOf<"owner"> {
+}
+/**
+ * Physically partition the entity's table per group (`groups/{name}/…`).
+ * This is the default whenever a `Group` field brand is present — declare it
+ * only for emphasis or with a JSDoc-configured group field.
+ */
+export interface GroupScoped extends ScopeOf<"group"> {
+}
+/**
+ * Keep rows in one shared table (row-level filters still apply). Use to opt a
+ * `Group`-branded entity out of the default per-group physical partitioning.
+ */
+export interface SharedStorage extends ScopeOf<"shared"> {
+}