rastack 0.0.51 → 0.0.52

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.52](https://github.com/theserverkid/reactapistack/compare/v0.0.51...v0.0.52) (2026-07-16)
+
 ### [0.0.51](https://github.com/theserverkid/reactapistack/compare/v0.0.50...v0.0.51) (2026-07-16)
 
 ### [0.0.50](https://github.com/theserverkid/reactapistack/compare/v0.0.49...v0.0.50) (2026-07-15)

package/auth/context.ts

@@ -0,0 +1,73 @@
+/**
+ * The React seam for `rastack/auth` — a tiny context carrying the signed-in
+ * {@link RastackAuth} and (when available) the compiled manifest, so the
+ * data-connected components can gate their affordances with zero wiring.
+ *
+ * `<RAStackProvider>` provides it automatically from its `auth` / `identity`
+ * config; `<RastackAuthProvider>` is the standalone provider for apps that
+ * don't use the runtime provider (e.g. a pure `remote`-mode admin screen).
+ *
+ * Deliberately JSX-free (plain `createElement`) so the pure model builders in
+ * `rastack/components` can import the hooks from a `.ts` module graph.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from "react";
+import {
+  policyFromManifest,
+  type ManifestLike,
+  type RastackAuth,
+  type ResourcePolicy,
+  type ResourceRef,
+} from "./core";
+
+export interface RastackAccessValue {
+  /** The signed-in identity, or `undefined` when no identity is wired up. */
+  auth?: RastackAuth;
+  /** `schema.rastack.json` (object or JSON string) for policy lookups. */
+  manifest?: ManifestLike | string;
+}
+
+const RastackAccessContext = createContext<RastackAccessValue>({});
+
+export interface RastackAuthProviderProps extends RastackAccessValue {
+  children?: ReactNode;
+}
+
+/** Provide the identity (and optionally the manifest) to the component tree. */
+export function RastackAuthProvider(props: RastackAuthProviderProps) {
+  const { auth, manifest, children } = props;
+  const value = useMemo<RastackAccessValue>(
+    () => ({ auth, manifest }),
+    [auth, manifest],
+  );
+  return createElement(RastackAccessContext.Provider, { value }, children);
+}
+
+/**
+ * The current identity, or `undefined` when none is provided — in which case
+ * the components stay ungated and the server remains the sole enforcer.
+ */
+export function useRastackAuth(): RastackAuth | undefined {
+  return useContext(RastackAccessContext).auth;
+}
+
+/**
+ * Look a resource's access policy up from the provided manifest. Returns
+ * `undefined` (⇒ the default `authenticated` gate) when no manifest is
+ * provided or the resource isn't in it.
+ */
+export function useResourcePolicy(
+  ref: ResourceRef | undefined,
+): ResourcePolicy | undefined {
+  const { manifest } = useContext(RastackAccessContext);
+  return useMemo(
+    () => (ref == null ? undefined : policyFromManifest(manifest, ref)),
+    [manifest, ref],
+  );
+}

package/auth/core.ts

@@ -0,0 +1,293 @@
+/**
+ * `rastack/auth` — the client-side authorization core.
+ *
+ * The server (`rastack-api-core`) is the enforcer: every request runs through
+ * the resource's `permission` gate, tenant scoping, and the row-level owner
+ * filter, identically on Lambda and in the in-browser WASM engine. What this
+ * module adds is the *client's view* of those same rules, so the UI can limit
+ * the paths it exposes — hide a delete button the server would 403, render a
+ * form read-only for an anonymous visitor — instead of discovering the answer
+ * as a failed request.
+ *
+ * Everything here is pure and mirrors `rust/rastack-api-core` exactly:
+ *   - {@link can} ⇔ `check_permission` + the RLS reachability check
+ *   - {@link bypassesRls} ⇔ `AuthContext::bypasses_rls`
+ *   - {@link ownsRow} ⇔ the owner filter `enforced_owner` derives
+ *
+ * These are UI affordances, never security: the engine re-checks every call.
+ */
+
+/** The resource-level permission gate. Unset means `authenticated` — secure by default. */
+export type PermissionPolicy =
+  "authenticated" | "authenticatedOrReadOnly" | "public";
+
+/** The five CRUD surfaces a policy is checked against. */
+export type AuthAction = "list" | "retrieve" | "create" | "update" | "delete";
+
+/**
+ * The signed-in identity, as the framework sees it everywhere — the TypeScript
+ * mirror of the Rust `AuthContext`. Build one from your auth library's session
+ * ({@link userAuth} / {@link authFromClaims}) and hand it to
+ * `<RAStackProvider auth={…}>`; the provider runs the WASM engine as this
+ * identity and the components gate their affordances with it.
+ */
+export interface RastackAuth {
+  /** The caller presented a verified identity. */
+  authenticated: boolean;
+  /** Verified subject — the Cognito `sub` claim. Also the tenant key. */
+  sub?: string;
+  /** Verified group claims (`cognito:groups`). */
+  groups?: string[];
+  /**
+   * Trusted contexts (the dev server with auth disabled) bypass every check,
+   * exactly like the Rust `AuthContext::trusted()`.
+   */
+  trusted?: boolean;
+}
+
+/** No identity. Only `public` resources (and reads of `authenticatedOrReadOnly`) pass. */
+export function anonymousAuth(): RastackAuth {
+  return { authenticated: false, groups: [] };
+}
+
+/** A verified end user. */
+export function userAuth(sub: string, groups: string[] = []): RastackAuth {
+  return { authenticated: true, sub, groups };
+}
+
+/** Full access, no row filters — local dev without auth configured. */
+export function trustedAuth(): RastackAuth {
+  return { authenticated: true, groups: [], trusted: true };
+}
+
+/**
+ * Build a {@link RastackAuth} from a decoded JWT payload (a Cognito ID/access
+ * token): `sub` becomes the subject, `cognito:groups` the groups.
+ */
+export function authFromClaims(claims: Record<string, unknown>): RastackAuth {
+  const sub = typeof claims.sub === "string" ? claims.sub : undefined;
+  const raw = claims["cognito:groups"];
+  const groups = Array.isArray(raw)
+    ? raw.filter((g): g is string => typeof g === "string")
+    : [];
+  return { authenticated: sub != null, sub, groups };
+}
+
+/** A resource's `access` block, as compiled into the manifest. */
+export interface ResourceAccess {
+  /** Field stamped with the owning subject; rows are filtered to their owner. */
+  ownerField?: string;
+  /** Field holding the owning group; rows are filtered to its members. */
+  groupField?: string;
+  /**
+   * `"owner"` physically partitions the table per identity
+   * (`tenants/{sub}/…`); `"group"` per group (`groups/{name}/…` — the default
+   * for group-owned datasets); `"shared"` keeps one table.
+   */
+  scope?: "owner" | "group" | "shared";
+  /** Token groups that bypass the row filters. */
+  adminGroups?: string[];
+}
+
+/**
+ * Everything access control needs to know about one resource — the
+ * `permission` gate plus the row-level `access` block. This is a structural
+ * subset of the manifest's `ResourceModel`, so a manifest resource assigns
+ * directly; {@link policyFromManifest} / {@link policyFromOpenApi} extract it.
+ */
+export interface ResourcePolicy {
+  permission?: PermissionPolicy | string;
+  access?: ResourceAccess;
+}
+
+/** Create/update/delete mutate; list/retrieve only read. */
+export function isWriteAction(action: AuthAction): boolean {
+  return action === "create" || action === "update" || action === "delete";
+}
+
+/**
+ * Whether this identity bypasses row-level security on the resource — trusted
+ * contexts and members of a configured admin group do.
+ */
+export function bypassesRls(
+  auth: RastackAuth,
+  policy: ResourcePolicy | undefined,
+): boolean {
+  if (auth.trusted) return true;
+  const adminGroups = policy?.access?.adminGroups ?? [];
+  const groups = auth.groups ?? [];
+  return adminGroups.some((g) => groups.includes(g));
+}
+
+/**
+ * The "is admin" role, driven from the token's group claims: whether this
+ * identity is in one of the resource's `adminGroups` (or is a trusted
+ * context) and therefore sees and acts on every row. An alias of
+ * {@link bypassesRls} with the name UIs actually want.
+ */
+export const isAdmin = bypassesRls;
+
+/**
+ * Whether the identity may perform `action` on the resource at all — the
+ * client-side mirror of the server's `permission` gate plus the row-level
+ * reachability rule (an RLS-protected resource needs a subject, unless the
+ * identity bypasses RLS).
+ *
+ * A `null`/`undefined` auth means "no identity is wired up" and gates nothing:
+ * the UI stays fully enabled and the server remains the sole enforcer. Pass
+ * {@link anonymousAuth} to model a signed-out visitor.
+ */
+export function can(
+  auth: RastackAuth | null | undefined,
+  policy: ResourcePolicy | undefined,
+  action: AuthAction,
+): boolean {
+  if (auth == null) return true;
+  if (auth.trusted) return true;
+
+  // The permission gate. Unset means `authenticated` — secure by default.
+  const write = isWriteAction(action);
+  const permitted =
+    policy?.permission === "public"
+      ? true
+      : policy?.permission === "authenticatedOrReadOnly"
+        ? auth.authenticated || !write
+        : auth.authenticated;
+  if (!permitted) return false;
+
+  // Row-level security / tenant scoping need a subject to resolve rows or the
+  // tenant view — without one the server answers 401.
+  const access = policy?.access;
+  const ownerSecured = Boolean(access?.ownerField) || access?.scope === "owner";
+  if (ownerSecured && auth.sub == null && !bypassesRls(auth, policy)) {
+    return false;
+  }
+
+  // Group-owned resources: reads outside any group just come back empty, but
+  // a write can never succeed — there is no group to place the row in or no
+  // row a membership guard would ever pass.
+  if (
+    access?.groupField &&
+    write &&
+    (auth.groups ?? []).length === 0 &&
+    !bypassesRls(auth, policy)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Whether the identity owns a specific row under the resource's row-level
+ * security — mirrors the row guards the server applies: the owner filter
+ * (`ownerField` must carry the caller's subject) *and* the group-membership
+ * filter (`groupField` must carry one of the caller's groups). Admin groups
+ * and trusted contexts pass unfiltered; rows of an unsecured resource are
+ * "owned" by everyone.
+ */
+export function ownsRow(
+  auth: RastackAuth | null | undefined,
+  policy: ResourcePolicy | undefined,
+  row: Record<string, unknown>,
+): boolean {
+  if (auth == null) return true;
+  if (bypassesRls(auth, policy)) return true;
+  const ownerField = policy?.access?.ownerField;
+  if (ownerField) {
+    if (auth.sub == null || String(row[ownerField] ?? "") !== auth.sub) {
+      return false;
+    }
+  }
+  const groupField = policy?.access?.groupField;
+  if (groupField) {
+    if (!(auth.groups ?? []).includes(String(row[groupField] ?? ""))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** {@link can} on the resource *and* {@link ownsRow} on the specific row. */
+export function canActOnRow(
+  auth: RastackAuth | null | undefined,
+  policy: ResourcePolicy | undefined,
+  action: AuthAction,
+  row: Record<string, unknown>,
+): boolean {
+  return can(auth, policy, action) && ownsRow(auth, policy, row);
+}
+
+// -- policy lookup --------------------------------------------------------
+
+/**
+ * The structural slice of `schema.rastack.json` the policy lookup reads.
+ * Deliberately loose (any object with a `resources` array) so a manifest
+ * however it was loaded — imported JSON, `JSON.parse`, the typed compiler
+ * output — assigns without casts.
+ */
+export interface ManifestLike {
+  resources?: Array<Record<string, unknown>>;
+}
+
+/** Accept `"app.model"` or `{ app, model }`. */
+export type ResourceRef = string | { app: string; model: string };
+
+function splitRef(ref: ResourceRef): { app: string; model: string } {
+  if (typeof ref !== "string") return ref;
+  const dot = ref.indexOf(".");
+  if (dot === -1)
+    throw new Error(`Invalid resource ref "${ref}" — expected "app.model".`);
+  return { app: ref.slice(0, dot), model: ref.slice(dot + 1) };
+}
+
+/**
+ * Extract a resource's {@link ResourcePolicy} from the compiled manifest
+ * (`schema.rastack.json`, object or JSON string), or `undefined` when the
+ * resource isn't found.
+ */
+export function policyFromManifest(
+  manifest: ManifestLike | string | null | undefined,
+  ref: ResourceRef,
+): ResourcePolicy | undefined {
+  if (manifest == null) return undefined;
+  const doc: ManifestLike =
+    typeof manifest === "string" ? JSON.parse(manifest) : manifest;
+  const { app, model } = splitRef(ref);
+  const resource = doc.resources?.find(
+    (r) => r.app === app && r.model === model,
+  );
+  if (!resource) return undefined;
+  const policy: ResourcePolicy = {};
+  if (resource.permission != null) {
+    policy.permission = resource.permission as string;
+  }
+  if (resource.access != null) {
+    policy.access = resource.access as ResourceAccess;
+  }
+  return policy;
+}
+
+/**
+ * Extract a resource's {@link ResourcePolicy} from the compiled OpenAPI
+ * document — the `x-rastack-permission` / `x-rastack-access` stamps on its
+ * `/api/{app}/v1/{model}/` operations.
+ */
+export function policyFromOpenApi(
+  doc: { paths?: Record<string, any> } | string | null | undefined,
+  ref: ResourceRef,
+): ResourcePolicy | undefined {
+  if (doc == null) return undefined;
+  const parsed: { paths?: Record<string, any> } =
+    typeof doc === "string" ? JSON.parse(doc) : doc;
+  const { app, model } = splitRef(ref);
+  const path = parsed.paths?.[`/api/${app}/v1/${model}/`];
+  if (!path) return undefined;
+  const operation = path.get ?? path.post ?? Object.values(path)[0];
+  if (!operation || typeof operation !== "object") return undefined;
+  const policy: ResourcePolicy = {};
+  const permission = (operation as any)["x-rastack-permission"];
+  if (permission != null) policy.permission = permission;
+  const access = (operation as any)["x-rastack-access"];
+  if (access != null) policy.access = access;
+  return policy;
+}

package/auth/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `rastack/auth` — the whole auth surface of the stack:
+ *
+ * - **Authoring** (types the compiler reads): the entity markers
+ *   (`IsAuthenticated`, `AdminGroups<…>`, `OwnerScoped`, `GroupScoped`, …)
+ *   and the `Owner` / `Group` access-control field brands.
+ * - **Runtime**: the TypeScript auth type ({@link RastackAuth}), the
+ *   client-side mirror of the server's authorization rules ({@link can},
+ *   row-level security helpers, policy lookup), and the React context the
+ *   provider and components share.
+ *
+ * See `docs/security-and-local-cache.md`.
+ */
+
+export * from "../src/define/auth";
+export * from "./core";
+export {
+  RastackAuthProvider,
+  useRastackAuth,
+  useResourcePolicy,
+  type RastackAccessValue,
+  type RastackAuthProviderProps,
+} from "./context";

package/components/auto-form/AutoForm.tsx

@@ -13,10 +13,11 @@ import {
   useAutoForm,
   type AutoFormFieldModel,
   type AutoFormModel,
+  type AutoFormModelOptions,
 } from "./use-auto-form";
-import type { AutoFormInputKind, AutoFormOptions } from "./fields";
+import type { AutoFormInputKind } from "./fields";
 
-export interface AutoFormProps extends AutoFormOptions {
+export interface AutoFormProps extends AutoFormModelOptions {
   /** The form hook result (`useUpdateXForm(...)`) driving the form. */
   form: AutoFormLike;
   submitLabel?: React.ReactNode;
@@ -61,6 +62,10 @@ export function AutoForm(props: AutoFormProps): React.JSX.Element {
     form,
     fields,
     exclude,
+    auth,
+    policy,
+    resource,
+    action,
     submitLabel = "Save",
     onCancel,
     cancelLabel = "Cancel",
@@ -72,7 +77,14 @@ export function AutoForm(props: AutoFormProps): React.JSX.Element {
     className,
   } = props;
 
-  const model = useAutoForm(form, { fields, exclude });
+  const model = useAutoForm(form, {
+    fields,
+    exclude,
+    auth,
+    policy,
+    resource,
+    action,
+  });
   const [touched, setTouched] = useState<Set<string>>(() => new Set());
   const [submitted, setSubmitted] = useState(false);
 
@@ -87,6 +99,7 @@ export function AutoForm(props: AutoFormProps): React.JSX.Element {
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
+    if (!model.canWrite) return;
     setSubmitted(true);
     model.submit();
     onSubmit?.();
@@ -210,18 +223,25 @@ export function AutoForm(props: AutoFormProps): React.JSX.Element {
       {children ? (
         children(model)
       ) : (
-        <div
-          style={{
-            display: "grid",
-            gridTemplateColumns: `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`,
-            gap: tokens.space.lg,
-          }}
+        // Authorization is enforced by the API; here it shapes the UI — an
+        // identity the policy denies writes to gets every control disabled.
+        <fieldset
+          disabled={!model.canWrite}
+          style={{ border: 0, margin: 0, padding: 0, minInlineSize: 0 }}
         >
-          {model.fields.map(renderField)}
-        </div>
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`,
+              gap: tokens.space.lg,
+            }}
+          >
+            {model.fields.map(renderField)}
+          </div>
+        </fieldset>
       )}
 
-      {!hideActions && !children ? (
+      {!hideActions && !children && model.canWrite ? (
         <div
           style={{
             display: "flex",

package/components/auto-form/use-auto-form.ts

@@ -12,6 +12,15 @@ import type React from "react";
 import type { FieldOption } from "../../hooks/form/interfaces";
 import type { AutoFormField, AutoFormLike } from "../types";
 import { humanizeKey } from "../util";
+import {
+  bypassesRls,
+  can,
+  useRastackAuth,
+  useResourcePolicy,
+  type RastackAuth,
+  type ResourcePolicy,
+  type ResourceRef,
+} from "../../auth";
 import {
   inputKindForFieldType,
   resolveFieldSpecs,
@@ -53,6 +62,13 @@ export interface AutoFormModel {
   isSubmitting: boolean;
   /** `true` when the form is valid and not mid-submit. */
   canSubmit: boolean;
+  /**
+   * Whether the current identity may write this resource at all — the client
+   * mirror of the server's `permission` gate + row-level security. `false`
+   * renders the form read-only (`<AutoForm>` disables every control and hides
+   * the actions row). Always `true` when no auth/policy is wired up.
+   */
+  canWrite: boolean;
   errors: Record<string, unknown>;
   /**
    * State-machine actions — feature-detected from `useForm(Entity)` results
@@ -61,13 +77,54 @@ export interface AutoFormModel {
   transitions: AutoFormTransitionModel[];
 }
 
+/** Authorization inputs shared by `useAutoForm` and `<AutoForm>`. */
+export interface AutoFormAuthOptions {
+  /**
+   * The identity to gate against. Defaults to the ambient identity from
+   * `<RAStackProvider auth={…}>` / `<RastackAuthProvider>`; pass `null` to
+   * opt out of gating for this form.
+   */
+  auth?: RastackAuth | null;
+  /** The resource's compiled `permission` + `access` policy. */
+  policy?: ResourcePolicy;
+  /**
+   * `"app.model"` — looks `policy` up from the provider's manifest when one
+   * is available (always the case in `local`/`s3` mode).
+   */
+  resource?: ResourceRef;
+  /** Which write this form performs. Default `"update"`. */
+  action?: "create" | "update";
+}
+
+export type AutoFormModelOptions = AutoFormOptions & AutoFormAuthOptions;
+
 /** Pure model assembly — see {@link useAutoForm}. Testable with a mock form. */
 export function buildAutoFormModel(
   form: AutoFormLike,
-  options: AutoFormOptions = {},
+  options: AutoFormModelOptions = {},
 ): AutoFormModel {
+  const auth = options.auth ?? undefined;
+  const policy = options.policy;
+  const canWrite = can(auth, policy, options.action ?? "update");
+
+  // The owner field is stamped from the verified token on create and
+  // immutable after that — never user-editable. Drop it from inferred field
+  // lists (an explicit `fields` entry still wins) unless the identity
+  // bypasses row-level security (admins may see whose row it is).
+  const ownerField = policy?.access?.ownerField;
+  const hideOwner =
+    ownerField != null &&
+    !options.fields?.length &&
+    auth != null &&
+    !bypassesRls(auth, policy);
+
   const fieldNames = Object.keys(form.formValues ?? {});
-  const specs = resolveFieldSpecs(fieldNames, options);
+  const specs = resolveFieldSpecs(fieldNames, {
+    ...options,
+    exclude: hideOwner
+      ? [...(options.exclude ?? []), ownerField]
+      : options.exclude,
+  });
 
   const fields: AutoFormFieldModel[] = specs.map((spec) => {
     const field = form.getFormField(spec.name);
@@ -102,16 +159,28 @@ export function buildAutoFormModel(
     submit: () => form.onSubmit(),
     reset: () => form.resetForm(),
     isSubmitting: form.isSubmitting,
-    canSubmit: !form.isSubmitDisabled && !form.isSubmitting,
+    canSubmit: canWrite && !form.isSubmitDisabled && !form.isSubmitting,
+    canWrite,
     errors: (form.errors as Record<string, unknown>) ?? {},
     transitions,
   };
 }
 
-/** React hook wrapper around {@link buildAutoFormModel}. */
+/**
+ * React hook wrapper around {@link buildAutoFormModel}. Auth handling is built
+ * in: the identity defaults to the ambient one from `<RAStackProvider
+ * auth={…}>`, and passing `resource: "app.model"` resolves the policy from the
+ * provider's manifest — so inside the provider, gating needs zero wiring.
+ */
 export function useAutoForm(
   form: AutoFormLike,
-  options: AutoFormOptions = {},
+  options: AutoFormModelOptions = {},
 ): AutoFormModel {
-  return buildAutoFormModel(form, options);
+  const ambientAuth = useRastackAuth();
+  const ambientPolicy = useResourcePolicy(options.resource);
+  return buildAutoFormModel(form, {
+    ...options,
+    auth: options.auth !== undefined ? options.auth : ambientAuth,
+    policy: options.policy ?? ambientPolicy,
+  });
 }