rastack 0.0.50 → 0.0.52

package/src/compile/entities.ts

@@ -25,7 +25,7 @@ import { applyTransitions, literalToValue } from "./analyze";
  * 2. **Datatypes come from the properties.** Each property's TypeScript type
  *    maps to a manifest scalar (`string` → string, `number` → float,
  *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
- *    type system with `DbConfig` brands from `rastack/types` —
+ *    type system with `DbConfig` brands from `rastack/db` —
  *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
  *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
  *    Optional / `| null` properties become nullable fields. On a class, a
@@ -166,7 +166,9 @@ export function analyzeEntities(
   }
   for (const decl of candidates) {
     if (jsdocTags(decl).has("rastackresource")) addRoot(decl);
-    else if (ts.isClassDeclaration(decl) && isDataClass(decl)) addRoot(decl);
+    else if (ts.isClassDeclaration(decl) && isDataClass(decl, checker)) {
+      addRoot(decl);
+    }
   }
 
   // 2. Transitive closure over FK references: an entity's entity-typed
@@ -190,7 +192,11 @@ export function analyzeEntities(
     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);
       }
     }
@@ -215,9 +221,14 @@ export function analyzeEntities(
     const fields: FieldModel[] = [];
     const relations: RelationModel[] = [];
 
+    let ownerField: string | undefined;
+    let groupField: string | undefined;
     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) continue; // has-many arrays are the reverse side of a FK
@@ -238,16 +249,53 @@ export function analyzeEntities(
         });
       } 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: NonNullable<ResourceModel["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: ResourceModel = {
       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
@@ -257,7 +305,9 @@ export function analyzeEntities(
   }
 
   resources.sort((a, b) =>
-    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+    a.app === b.app
+      ? a.model.localeCompare(b.model)
+      : a.app.localeCompare(b.app),
   );
   return { resources, diagnostics, types };
 }
@@ -344,13 +394,24 @@ function entityBehindType(
 /**
  * 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: ts.ClassDeclaration): boolean {
-  if (decl.heritageClauses?.length) return false;
+function isDataClass(
+  decl: ts.ClassDeclaration,
+  checker: ts.TypeChecker,
+): boolean {
+  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)
@@ -379,6 +440,10 @@ interface PropInfo {
   inverse?: boolean;
   /** Unsupported type — reported as a warning and skipped. */
   skip?: string;
+  /** This column is the resource's `access.ownerField`. */
+  owner?: boolean;
+  /** This column is the resource's `access.groupField`. */
+  group?: boolean;
 }
 
 /** A column-shaped member: an interface property or a class instance field. */
@@ -449,13 +514,19 @@ function analyzeProperty(
   if (ts.isUnionTypeNode(typeNode)) {
     const arms = typeNode.types.filter((t) => {
       const isNullish =
-        (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword) ||
+        (ts.isLiteralTypeNode(t) &&
+          t.literal.kind === ts.SyntaxKind.NullKeyword) ||
         t.kind === ts.SyntaxKind.UndefinedKeyword;
       if (isNullish) nullable = true;
       return !isNullish;
     });
     if (arms.length > 1 && arms.every(isStringish)) {
-      return scalarProp(name, "string", configFromTags(jsdocTags(member)), nullable);
+      return scalarProp(
+        name,
+        "string",
+        configFromTags(jsdocTags(member)),
+        nullable,
+      );
     }
     if (arms.length !== 1) {
       return { name, nullable, skip: "unsupported union type — skipped" };
@@ -497,7 +568,8 @@ function analyzeProperty(
 function initializerDefault(
   member: EntityProp,
 ): string | number | boolean | undefined {
-  if (!ts.isPropertyDeclaration(member) || !member.initializer) return undefined;
+  if (!ts.isPropertyDeclaration(member) || !member.initializer)
+    return undefined;
   const init = member.initializer;
   if (ts.isStringLiteralLike(init)) return init.text;
   if (ts.isNumericLiteral(init)) return Number(init.text);
@@ -558,7 +630,10 @@ function scalarProp(
   if (config.primaryKey) field.primaryKey = true;
   if (nullable) field.null = true;
   if (config.default !== undefined) field.default = config.default;
-  return { name, nullable, field };
+  const info: PropInfo = { name, nullable, field };
+  if (config.owner) info.owner = true;
+  if (config.group) info.group = true;
+  return info;
 }
 
 // -- column configuration -------------------------------------------------------
@@ -572,6 +647,10 @@ interface ColumnConfig {
   unique?: boolean;
   primaryKey?: boolean;
   default?: unknown;
+  /** `string & Owner` / `@owner` — this column records the owning subject. */
+  owner?: boolean;
+  /** `string & Group` / `@group` — this column records the owning group. */
+  group?: boolean;
 }
 
 /**
@@ -601,6 +680,8 @@ function configFromType(
   if (prop("datetime")) config.datetime = true;
   if (prop("unique")) 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;
   const dflt = prop("default");
@@ -617,6 +698,8 @@ function configFromTags(tags: Map<string, string>): ColumnConfig {
   if (tags.has("datetime")) config.datetime = true;
   if (tags.has("unique")) 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;
   const dflt = tags.get("default");
@@ -650,7 +733,8 @@ function unwrapParens(node: ts.TypeNode): ts.TypeNode {
 /** `string`, a string-literal type, or a template literal type. */
 function isStringish(node: ts.TypeNode): boolean {
   if (node.kind === ts.SyntaxKind.StringKeyword) return true;
-  if (ts.isLiteralTypeNode(node) && ts.isStringLiteralLike(node.literal)) return true;
+  if (ts.isLiteralTypeNode(node) && ts.isStringLiteralLike(node.literal))
+    return true;
   return ts.isTemplateLiteralTypeNode(node);
 }
 
@@ -660,7 +744,8 @@ function arrayElement(node: ts.TypeNode): ts.TypeNode | undefined {
   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];
@@ -685,7 +770,8 @@ function entityNaming(decl: EntityDecl): EntityNaming {
   // 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);
+    tags.get("rastackmodel") ||
+    stripped.charAt(0).toLowerCase() + stripped.slice(1);
   const app =
     tags.get("rastackapp") ||
     path
@@ -695,7 +781,11 @@ function entityNaming(decl: EntityDecl): EntityNaming {
 
   const naming: EntityNaming = { app, model };
   const search = tags.get("rastacksearch");
-  if (search) naming.search = search.split(",").map((s) => s.trim()).filter(Boolean);
+  if (search)
+    naming.search = search
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
   const permission = tags.get("rastackpermission");
   if (
     permission === "authenticatedOrReadOnly" ||
@@ -707,6 +797,90 @@ function entityNaming(decl: EntityDecl): EntityNaming {
   return naming;
 }
 
+// -- access policy (auth as types) ---------------------------------------------
+
+/** The phantom keys the `rastack/auth` entity markers carry. */
+const MARKER_PROPS = [
+  "__rastackPermission",
+  "__rastackAdminGroups",
+  "__rastackScope",
+] as const;
+
+/** Whether a heritage type is an auth marker (policy, not behaviour). */
+function isAccessMarker(type: ts.Type): boolean {
+  return MARKER_PROPS.some((p) => type.getProperty(p));
+}
+
+/** An entity's access policy, however it was authored. */
+interface EntityPolicy {
+  permission?: ResourceModel["permission"];
+  adminGroups?: string[];
+  scope?: "owner" | "group" | "shared";
+}
+
+/**
+ * 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: EntityDecl,
+  checker: ts.TypeChecker,
+  naming: EntityNaming,
+): EntityPolicy {
+  const policy: EntityPolicy = {};
+  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: string): string[] => {
+        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 is ts.StringLiteralType => 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: ts.Node): Map<string, string> {
   const tags = new Map<string, string>();

package/src/compile/model.ts

@@ -5,12 +5,7 @@
  */
 
 export type ScalarType =
-  | "string"
-  | "int"
-  | "float"
-  | "bool"
-  | "datetime"
-  | "uuid";
+  "string" | "int" | "float" | "bool" | "datetime" | "uuid";
 
 export type FieldType = ScalarType | "fk";
 
@@ -60,12 +55,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/src/compile/openapi.ts

@@ -257,16 +257,24 @@ function syncStamp(operation: any, resource: ResourceModel, verb: string): any {
 }
 
 /**
- * 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: any, resource: ResourceModel): void {
+  if (resource.permission) {
+    operation["x-rastack-permission"] = resource.permission;
+  }
   const access = resource.access;
   if (!access) return;
   const stamp: any = {};
   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/src/compile/program.ts

@@ -4,7 +4,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.
  */
@@ -26,7 +27,11 @@ export function createProgram(fileNames: string[]): ts.Program {
     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")],
     },
   };
 
@@ -41,5 +46,7 @@ export function resourceSourceFiles(
   const wanted = new Set(fileNames.map((f) => path.resolve(f)));
   return program
     .getSourceFiles()
-    .filter((sf) => !sf.isDeclarationFile && wanted.has(path.resolve(sf.fileName)));
+    .filter(
+      (sf) => !sf.isDeclarationFile && wanted.has(path.resolve(sf.fileName)),
+    );
 }

package/src/define/auth.ts

@@ -0,0 +1,28 @@
+/**
+ * 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/src/define/db.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;
@@ -48,11 +48,33 @@ export interface Unique extends DbConfig<{ unique: true }> {}
 export interface PrimaryKey extends DbConfig<{ primaryKey: true }> {}
 
 /** Maximum length for string columns: `string & MaxLength<120>`. */
-export interface MaxLength<N extends number> extends DbConfig<{ maxLength: N }> {}
+export interface MaxLength<N extends number> extends DbConfig<{
+  maxLength: N;
+}> {}
 
 /** Server-side default value: `string & Default<"scheduled">`, `number & Default<0>`. */
-export interface Default<V extends string | number | boolean>
-  extends DbConfig<{ default: V }> {}
+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 }>;