rastack 0.0.20 → 0.0.22

package/src/compile/model.ts

@@ -51,6 +51,18 @@ export interface AdminModel {
   listDisplay?: string[];
 }
 
+/**
+ * Row-level access control, enforced by `rad-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.
+ */
+export interface AccessModel {
+  ownerField?: string;
+  scope?: "owner" | "shared";
+  adminGroups?: string[];
+}
+
 export interface ResourceModel {
   app: string;
   model: string;
@@ -61,6 +73,7 @@ export interface ResourceModel {
   search?: string[];
   ordering?: string[];
   permission?: string;
+  access?: AccessModel;
 }
 
 export interface Manifest {

package/src/compile/openapi.ts

@@ -6,7 +6,8 @@ import { FieldModel, ResourceModel } from "./model";
  * on — `/api/{app}/v1/{model}/` URL segments and the `x-rastack-sync*` vendor
  * extensions — so those packages are unchanged. Foreign keys additionally carry
  * a new `x-rastack-relation` extension so downstream tooling (and the admin) can
- * follow relations.
+ * follow relations, and access-controlled resources carry `x-rastack-access`
+ * (owner field + tenant scope) so the client cache can partition per identity.
  */
 export function buildOpenApi(resources: ResourceModel[]): any {
   const paths: Record<string, any> = {};
@@ -231,6 +232,7 @@ function queryParam(name: string, type: string): any {
  * local resource replicates.
  */
 function syncStamp(operation: any, resource: ResourceModel, verb: string): any {
+  accessStamp(operation, resource);
   const sync = resource.sync;
   if (!sync || sync.mode !== "local") return operation;
 
@@ -242,6 +244,20 @@ function syncStamp(operation: any, resource: ResourceModel, verb: string): any {
   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.
+ */
+function accessStamp(operation: any, resource: ResourceModel): void {
+  const access = resource.access;
+  if (!access) return;
+  const stamp: any = {};
+  if (access.ownerField) stamp.ownerField = access.ownerField;
+  if (access.scope) stamp.scope = access.scope;
+  if (Object.keys(stamp).length) operation["x-rastack-access"] = stamp;
+}
+
 function isConfirmed(
   confirmed: string[] | undefined,
   verb: string,

package/src/define/index.ts

@@ -112,6 +112,26 @@ export interface SyncOptions {
   clientIds?: boolean;
 }
 
+/**
+ * Row-level access control. Enforced by `rad-api-core`, so the rules are
+ * identical on the server (Lambda / `rad serve`) and in the in-browser WASM
+ * engine.
+ *
+ * - `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.
+ * - `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}"}/*`.
+ * - `adminGroups` — token groups (`cognito:groups`) that bypass row filters.
+ */
+export interface AccessOptions {
+  ownerField?: string;
+  scope?: "owner" | "shared";
+  adminGroups?: string[];
+}
+
 export interface ResourceOptions {
   /** DRF-style search fields. */
   search?: string[];
@@ -123,6 +143,8 @@ export interface ResourceOptions {
   sync?: SyncOptions;
   /** Access policy (secure by default). */
   permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
+  /** Row-level security + physical tenant partitioning. */
+  access?: AccessOptions;
 }
 
 /**

package/test/cache.spec.ts

@@ -0,0 +1,263 @@
+import {
+  AccessRevokedError,
+  CacheExpiredError,
+  createEncryptedCacheStorage,
+  generateEncryptionKey,
+  IcebergFileCache,
+  MemoryCacheStorage,
+  purgeLocalData,
+  WarehouseFileSource,
+} from "../cache";
+
+/**
+ * The cache is exercised against an in-memory "object store" that counts
+ * fetches — the observable contract is Iceberg's: the version hint is the only
+ * file re-fetched once cached copies exist, immutable snapshot/data files are
+ * fetched exactly once, and revoked access deletes the identity's cache.
+ */
+
+const encoder = new TextEncoder();
+
+class FakeWarehouse implements WarehouseFileSource {
+  files = new Map<string, Uint8Array>();
+  fetches: string[] = [];
+  revoked = false;
+  offline = false;
+
+  async fetchFile(key: string): Promise<Uint8Array | null> {
+    if (this.revoked) throw new AccessRevokedError("revoked", 403);
+    if (this.offline) throw new Error("network unreachable");
+    this.fetches.push(key);
+    return this.files.get(key) ?? null;
+  }
+
+  /** Commit snapshot `version` for the table with the given data files. */
+  commit(prefix: string, version: number, dataFiles: Record<string, object[]>) {
+    this.files.set(
+      `${prefix}/metadata/version-hint.text`,
+      encoder.encode(String(version)),
+    );
+    this.files.set(
+      `${prefix}/metadata/v${version}.metadata.json`,
+      encoder.encode(
+        JSON.stringify({
+          format: "rad-iceberg-v1",
+          data_files: Object.keys(dataFiles),
+          next_int_id: 99,
+        }),
+      ),
+    );
+    for (const [rel, rows] of Object.entries(dataFiles)) {
+      this.files.set(`${prefix}/${rel}`, encoder.encode(JSON.stringify(rows)));
+    }
+  }
+}
+
+class FakeEngine {
+  seeded: string[] = [];
+  async seedFile(key: string): Promise<void> {
+    this.seeded.push(key);
+  }
+}
+
+const RESOURCES = [{ app: "airports", model: "airport" }];
+const PREFIX = "airports.db/airport";
+
+function makeCache(source: FakeWarehouse, identity = "alice-sub") {
+  const storage = new MemoryCacheStorage();
+  return {
+    storage,
+    cache: new IcebergFileCache({ storage, source, identity }),
+  };
+}
+
+describe("IcebergFileCache", () => {
+  it("cold seed fetches the Iceberg tree and feeds it to the engine", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1, code: "JFK" }] });
+    const { cache } = makeCache(source);
+    const engine = new FakeEngine();
+
+    const stats = await cache.seed(engine, RESOURCES);
+
+    expect(stats).toEqual({ tables: 1, fromCache: 0, fetched: 3 });
+    expect(engine.seeded).toEqual([
+      `${PREFIX}/metadata/version-hint.text`,
+      `${PREFIX}/metadata/v1.metadata.json`,
+      `${PREFIX}/data/v1.json`,
+    ]);
+  });
+
+  it("warm seed with no new commit refetches only the version hint", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const { cache } = makeCache(source);
+
+    await cache.seed(new FakeEngine(), RESOURCES);
+    source.fetches = [];
+
+    const stats = await cache.seed(new FakeEngine(), RESOURCES);
+    // One small network read (the pointer); the immutable files came from cache.
+    expect(source.fetches).toEqual([`${PREFIX}/metadata/version-hint.text`]);
+    expect(stats).toEqual({ tables: 1, fromCache: 2, fetched: 1 });
+  });
+
+  it("a new snapshot fetches only unseen files and prunes superseded ones", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const { cache, storage } = makeCache(source);
+    await cache.seed(new FakeEngine(), RESOURCES);
+
+    // Update/delete rewrite a compacted snapshot: v2 supersedes v1's file.
+    source.commit(PREFIX, 2, { "data/v2.json": [{ id: 1, name: "x" }] });
+    source.fetches = [];
+
+    const engine = new FakeEngine();
+    await cache.seed(engine, RESOURCES);
+
+    expect(source.fetches).toEqual([
+      `${PREFIX}/metadata/version-hint.text`,
+      `${PREFIX}/metadata/v2.metadata.json`,
+      `${PREFIX}/data/v2.json`,
+    ]);
+    expect(engine.seeded).toContain(`${PREFIX}/data/v2.json`);
+    // The superseded snapshot's files no longer occupy the device.
+    const keys = await storage.keys("");
+    expect(keys.some((k) => k.includes("v1.metadata.json"))).toBe(false);
+    expect(keys.some((k) => k.includes("data/v1.json"))).toBe(false);
+  });
+
+  it("falls back to the cached pointer when offline", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const { cache } = makeCache(source);
+    await cache.seed(new FakeEngine(), RESOURCES);
+
+    source.offline = true;
+    const engine = new FakeEngine();
+    const stats = await cache.seed(engine, RESOURCES);
+    expect(stats.tables).toBe(1);
+    expect(stats.fetched).toBe(0);
+    expect(engine.seeded).toHaveLength(3);
+  });
+
+  it("revoked access deletes the identity's cached data and surfaces the error", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const { cache, storage } = makeCache(source);
+    await cache.seed(new FakeEngine(), RESOURCES);
+    expect(await storage.keys("alice-sub::")).not.toHaveLength(0);
+
+    source.revoked = true;
+    await expect(cache.seed(new FakeEngine(), RESOURCES)).rejects.toThrow(
+      AccessRevokedError,
+    );
+    // Nothing of alice's survives on the device.
+    expect(await storage.keys("alice-sub::")).toHaveLength(0);
+  });
+
+  it("enforces the offline-retention bound: stale cache is deleted, not served", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const storage = new MemoryCacheStorage();
+    let clock = 1_000_000;
+    const cache = new IcebergFileCache({
+      storage,
+      source,
+      identity: "alice",
+      maxOfflineMs: 60_000,
+      now: () => clock,
+    });
+    await cache.seed(new FakeEngine(), RESOURCES);
+
+    // Offline but within the bound: cached data still serves.
+    source.offline = true;
+    clock += 30_000;
+    expect((await cache.seed(new FakeEngine(), RESOURCES)).tables).toBe(1);
+
+    // Past the bound: the cache refuses AND deletes the identity's data.
+    clock += 60_001;
+    await expect(cache.seed(new FakeEngine(), RESOURCES)).rejects.toThrow(
+      CacheExpiredError,
+    );
+    expect(await storage.keys("alice::")).toHaveLength(0);
+
+    // Back online: re-verification restores service from the source.
+    source.offline = false;
+    expect((await cache.seed(new FakeEngine(), RESOURCES)).tables).toBe(1);
+  });
+
+  it("namespaces isolate identities sharing one device", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1 }] });
+    const storage = new MemoryCacheStorage();
+    const alice = new IcebergFileCache({ storage, source, identity: "alice" });
+    const bob = new IcebergFileCache({ storage, source, identity: "bob" });
+
+    await alice.seed(new FakeEngine(), RESOURCES);
+    await bob.seed(new FakeEngine(), RESOURCES);
+
+    await purgeLocalData({ identity: "alice", cacheStorage: storage });
+    expect(await storage.keys("alice::")).toHaveLength(0);
+    expect(await storage.keys("bob::")).not.toHaveLength(0);
+  });
+});
+
+describe("createEncryptedCacheStorage", () => {
+  it("round-trips values while storing only ciphertext", async () => {
+    const inner = new MemoryCacheStorage();
+    const key = await generateEncryptionKey();
+    const storage = createEncryptedCacheStorage(inner, key);
+    const plaintext = encoder.encode("sensitive row data");
+
+    await storage.put("k", plaintext);
+    expect(new Uint8Array((await storage.get("k"))!)).toEqual(plaintext);
+
+    // What actually hits the device is sealed: different bytes, and a fresh
+    // random IV means two writes of the same value differ too.
+    const sealed1 = (await inner.get("k"))!;
+    expect(Buffer.from(sealed1).includes(Buffer.from(plaintext))).toBe(false);
+    await storage.put("k", plaintext);
+    expect((await inner.get("k"))!).not.toEqual(sealed1);
+  });
+
+  it("treats undecryptable bytes as a cache miss, never as data", async () => {
+    const inner = new MemoryCacheStorage();
+    const storage = createEncryptedCacheStorage(inner, await generateEncryptionKey());
+    await storage.put("k", encoder.encode("secret"));
+
+    // Read back under a different key → miss.
+    const other = createEncryptedCacheStorage(inner, await generateEncryptionKey());
+    expect(await other.get("k")).toBeNull();
+
+    // Tampered ciphertext → authenticated decryption fails → miss.
+    const sealed = (await inner.get("k"))!;
+    sealed[sealed.length - 1] ^= 0xff;
+    await inner.put("k", sealed);
+    expect(await storage.get("k")).toBeNull();
+  });
+
+  it("works end-to-end as the IcebergFileCache storage", async () => {
+    const source = new FakeWarehouse();
+    source.commit(PREFIX, 1, { "data/v1.json": [{ id: 1, code: "JFK" }] });
+    const inner = new MemoryCacheStorage();
+    const cache = new IcebergFileCache({
+      storage: createEncryptedCacheStorage(inner, await generateEncryptionKey()),
+      source,
+      identity: "alice",
+    });
+
+    await cache.seed(new FakeEngine(), RESOURCES);
+    source.fetches = [];
+    const stats = await cache.seed(new FakeEngine(), RESOURCES);
+    // Warm-cache behaviour is unchanged by encryption.
+    expect(stats).toEqual({ tables: 1, fromCache: 2, fetched: 1 });
+    // And nothing readable sits on the device.
+    const stored = await Promise.all(
+      (await inner.keys("alice::")).map((k) => inner.get(k)),
+    );
+    for (const bytes of stored) {
+      expect(Buffer.from(bytes!).includes(Buffer.from("JFK"))).toBe(false);
+    }
+  });
+});

package/test/compile.spec.ts

@@ -45,6 +45,14 @@ export const Gate = resource("airports", "gate", {
 export const Booking = resource("airports", "booking", {
   reference: s.string({ maxLength: 12 }),
 }, { sync: { mode: "local", clientIds: true } });
+
+export const Itinerary = resource("airports", "itinerary", {
+  owner: s.string({ maxLength: 64 }),
+  notes: s.string({ maxLength: 500 }),
+}, {
+  permission: "authenticated",
+  access: { ownerField: "owner", scope: "owner", adminGroups: ["staff"] },
+});
 `;
 
 function findResource(
@@ -112,6 +120,21 @@ describe("rad compile — resource analysis & FK inference", () => {
     });
   });
 
+  it("captures row-level access config (ownerField / scope / adminGroups)", () => {
+    const resources = analyzeResources(resourcesDir);
+    const itinerary = findResource(resources, "airports", "itinerary");
+
+    expect(itinerary.permission).toBe("authenticated");
+    expect(itinerary.access).toEqual({
+      ownerField: "owner",
+      scope: "owner",
+      adminGroups: ["staff"],
+    });
+
+    // Resources without an access block stay unstamped.
+    expect(findResource(resources, "airports", "airport").access).toBeUndefined();
+  });
+
   it("reports no collisions for a valid graph", () => {
     const resources = analyzeResources(resourcesDir);
     expect(collisions(resources)).toEqual([]);
@@ -132,7 +155,7 @@ describe("rad compile — OpenAPI emission", () => {
     const result = compile(resourcesDir, outDir);
     expect(existsSync(join(outDir, "schema.rad.json"))).toBe(true);
     expect(existsSync(join(outDir, "openapi.json"))).toBe(true);
-    expect(result.manifest.resources.length).toBe(5);
+    expect(result.manifest.resources.length).toBe(6);
   });
 
   it("emits the /api/{app}/v1/{model}/ contract with FK + sync extensions", () => {
@@ -162,6 +185,20 @@ describe("rad compile — OpenAPI emission", () => {
     expect(
       doc.paths["/api/airports/v1/booking/"].post["x-rastack-sync-client-ids"],
     ).toBe(true);
+
+    // Access-controlled resource carries the access extension on every op.
+    const itineraryList = doc.paths["/api/airports/v1/itinerary/"];
+    expect(itineraryList.get["x-rastack-access"]).toEqual({
+      ownerField: "owner",
+      scope: "owner",
+    });
+    expect(
+      doc.paths["/api/airports/v1/itinerary/{id}/"].delete["x-rastack-access"],
+    ).toEqual({ ownerField: "owner", scope: "owner" });
+    // Unscoped resources stay unstamped.
+    expect(
+      doc.paths["/api/airports/v1/airport/"].get["x-rastack-access"],
+    ).toBeUndefined();
   });
 
   it("round-trips through the existing hooks codegen", async () => {