@pramen/server 0.0.7 → 0.0.8

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
 export { createApp } from "./sdk/app";

package/dist/index.js

@@ -7,7 +7,7 @@
 // which only exists in the Workers runtime; keeping it separate lets the CLI, tests,
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";

package/dist/runtime/db.d.ts

@@ -120,6 +120,10 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private assertReadableWhere;
     private selectRaw;
     private jsonColsOf;
+    /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
+    private hiddenColsOf;
+    /** Drop hidden columns from a row (copying only if any are present). */
+    private stripHidden;
     /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
      * `vals`. Returns the columns it filled — server-minted, so the insert path treats
      * them like forced `set` values (bypassing the writable-field ACL check). */
@@ -145,7 +149,8 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
      * would: the caller's readable fields for this row, PLUS the columns they just
      * wrote (which they already know) and the primary key (so a write-only caller
      * still gets the generated id). Full read access -> the whole row; SYSTEM -> as-is.
-     * This makes create/update echoes field-ACL-safe without ever collapsing to {}. */
+     * This makes create/update echoes field-ACL-safe without ever collapsing to {}.
+     * Hidden columns are never echoed, even when written or under SYSTEM. */
     private projectWrite;
     /** Update a row by id. ACL row-scope is AND-ed into the WHERE, so a caller can
      * only update rows within scope; returns undefined if none matched. */

package/dist/runtime/db.js

@@ -264,6 +264,25 @@ export class Db {
             .filter(([, f]) => f.type === "json" || f.type === "fileRef")
             .map(([n]) => n);
     }
+    /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
+    hiddenColsOf(table) {
+        const fields = this.schema[table]?.fields;
+        if (!fields)
+            return [];
+        return Object.entries(fields)
+            .filter(([, f]) => f.hidden)
+            .map(([n]) => n);
+    }
+    /** Drop hidden columns from a row (copying only if any are present). */
+    stripHidden(table, row) {
+        const hidden = this.hiddenColsOf(table);
+        if (hidden.length === 0)
+            return row;
+        const out = { ...row };
+        for (const c of hidden)
+            delete out[c];
+        return out;
+    }
     /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
      * `vals`. Returns the columns it filled — server-minted, so the insert path treats
      * them like forced `set` values (bypassing the writable-field ACL check). */
@@ -325,7 +344,8 @@ export class Db {
     }
     /** Fetch one row by id within an ACL row-scope (for per-row write evaluation). */
     async fetchOne(from, id, scopeWhere) {
-        const where = scopeWhere ? and(eq("id", id), scopeWhere) : eq("id", id);
+        const pk = this.pkOf(from);
+        const where = scopeWhere ? and(eq(pk, id), scopeWhere) : eq(pk, id);
         const { sql, params } = compileSelect({ from, where, limit: 1 }, this.dialect);
         return this.decodeRow(from, (await this.driver.exec(sql, params))[0]);
     }
@@ -333,10 +353,11 @@ export class Db {
         const relNames = withSel ? Object.keys(withSel).filter((k) => withSel[k]) : [];
         for (const relName of relNames)
             await this.loadRelation(from, raw, relName);
+        // Hidden columns are stripped even under an unrestricted/SYSTEM scope (never readable).
         if (scope.fields === null)
-            return raw; // base unrestricted -> no per-row narrowing possible
+            return raw.map((r) => this.stripHidden(from, r));
         return raw.map((r) => {
-            const projected = projectRow(r, effectiveFields(scope, r, this.acl.identity));
+            const projected = this.stripHidden(from, projectRow(r, effectiveFields(scope, r, this.acl.identity)));
             for (const relName of relNames)
                 projected[relName] = r[relName]; // relations survive projection
             return projected;
@@ -382,7 +403,7 @@ export class Db {
             // parent[column] -> target.id
             const keys = [...new Set(rows.map((r) => r[rel.column]).filter((v) => v != null))];
             const byId = new Map();
-            for (const { key, row } of await fetchBy("id", keys))
+            for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys))
                 byId.set(key, row);
             for (const r of rows)
                 r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
@@ -428,19 +449,22 @@ export class Db {
      * would: the caller's readable fields for this row, PLUS the columns they just
      * wrote (which they already know) and the primary key (so a write-only caller
      * still gets the generated id). Full read access -> the whole row; SYSTEM -> as-is.
-     * This makes create/update echoes field-ACL-safe without ever collapsing to {}. */
+     * This makes create/update echoes field-ACL-safe without ever collapsing to {}.
+     * Hidden columns are never echoed, even when written or under SYSTEM. */
     projectWrite(table, row, writtenCols) {
         if (this.acl.system)
-            return row;
+            return this.stripHidden(table, row);
         const visible = new Set([this.pkOf(table), ...writtenCols]);
         const readScope = this.scopeFor(table, "read");
         if (readScope.allowed) {
             const readable = effectiveFields(readScope, row, this.acl.identity);
             if (readable === null)
-                return row; // unrestricted read -> echo everything
+                return this.stripHidden(table, row); // unrestricted read -> echo everything (minus hidden)
             for (const f of readable)
                 visible.add(f);
         }
+        for (const c of this.hiddenColsOf(table))
+            visible.delete(c);
         return projectRow(row, [...visible]);
     }
     /** Update a row by id. ACL row-scope is AND-ed into the WHERE, so a caller can
@@ -478,7 +502,7 @@ export class Db {
         })
             .join(", ");
         params.push(this.dialect.encode(id));
-        let sql = `UPDATE ${this.dialect.id(table)} SET ${assignments} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(params.length)}`;
+        let sql = `UPDATE ${this.dialect.id(table)} SET ${assignments} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(params.length)}`;
         sql += this.scopeClause(scope.where, params);
         sql += this.returningClause("*");
         const updated = this.decodeRow(table, (await this.driver.exec(sql, params))[0]);
@@ -492,9 +516,9 @@ export class Db {
         if (!scope.allowed)
             throw new AclDenied(table, "delete");
         const params = [this.dialect.encode(id)];
-        let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(1)}`;
+        let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(1)}`;
         sql += this.scopeClause(scope.where, params);
-        sql += this.returningClause("id");
+        sql += this.returningClause("*");
         return (await this.driver.exec(sql, params)).length > 0;
     }
     /** Escape hatch — raw SQL, NOT ACL-checked. For system/internal use only. */

package/dist/sdk/schema.d.ts

@@ -24,6 +24,12 @@ export interface FieldDef {
      * rebuilds the table, copying data from the old column. A diff cannot tell a
      * rename from a drop+add, so the rename must be declared explicitly. */
     readonly renamedFrom?: string;
+    /** Never project this column on any ORM read — find/get, mutation echoes, relation
+     * loads, and the SYSTEM-mode admin data API all strip it, even under a full-access
+     * (allow()) or SYSTEM scope. Writable on insert/update, and still visible to raw
+     * `ctx.db.exec` (the escape hatch credential code uses). For secrets/internal
+     * columns like a password hash. Set by the `hidden()` modifier. */
+    readonly hidden?: boolean;
 }
 declare const builders: {
     id: () => {
@@ -124,6 +130,13 @@ export declare function unique<F extends FieldDef>(field: F): F & {
 export declare function indexed<F extends FieldDef>(field: F): F & {
     readonly index: true;
 };
+/** Mark a column never-readable through the ORM: stripped from every read projection
+ * (find/get, mutation echoes, relation loads, admin data) even under full/SYSTEM
+ * access. Still writable, and still visible to raw `ctx.db.exec`. For secrets such as
+ * a password hash, e.g. `passwordHash: hidden(t.text())`. */
+export declare function hidden<F extends FieldDef>(field: F): F & {
+    readonly hidden: true;
+};
 /** A raw-SQL column DEFAULT (emitted unquoted in the DDL), produced by the `expr`
  * helpers below. Distinct from a literal default so `defaultTo` can render
  * `DEFAULT datetime('now')` rather than the quoted string `DEFAULT 'datetime(...)'`. */

package/dist/sdk/schema.js

@@ -57,6 +57,13 @@ export function unique(field) {
 export function indexed(field) {
     return { ...field, index: true };
 }
+/** Mark a column never-readable through the ORM: stripped from every read projection
+ * (find/get, mutation echoes, relation loads, admin data) even under full/SYSTEM
+ * access. Still writable, and still visible to raw `ctx.db.exec`. For secrets such as
+ * a password hash, e.g. `passwordHash: hidden(t.text())`. */
+export function hidden(field) {
+    return { ...field, hidden: true };
+}
 /** A raw-SQL column DEFAULT (emitted unquoted in the DDL), produced by the `expr`
  * helpers below. Distinct from a literal default so `defaultTo` can render
  * `DEFAULT datetime('now')` rather than the quoted string `DEFAULT 'datetime(...)'`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -8,7 +8,7 @@
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type {
   DefaultValue,

package/src/runtime/db.ts

@@ -385,6 +385,24 @@ export class Db<S extends SchemaDef = SchemaDef> {
       .map(([n]) => n);
   }
 
+  /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
+  private hiddenColsOf(table: string): string[] {
+    const fields = this.schema[table]?.fields;
+    if (!fields) return [];
+    return Object.entries(fields)
+      .filter(([, f]) => (f as FieldDef).hidden)
+      .map(([n]) => n);
+  }
+
+  /** Drop hidden columns from a row (copying only if any are present). */
+  private stripHidden(table: string, row: Row): Row {
+    const hidden = this.hiddenColsOf(table);
+    if (hidden.length === 0) return row;
+    const out = { ...row };
+    for (const c of hidden) delete out[c];
+    return out;
+  }
+
   /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
    * `vals`. Returns the columns it filled — server-minted, so the insert path treats
    * them like forced `set` values (bypassing the writable-field ACL check). */
@@ -444,7 +462,8 @@ export class Db<S extends SchemaDef = SchemaDef> {
 
   /** Fetch one row by id within an ACL row-scope (for per-row write evaluation). */
   private async fetchOne(from: string, id: Id, scopeWhere: SqlExpr | null): Promise<Row | undefined> {
-    const where = scopeWhere ? and(eq("id", id), scopeWhere) : eq("id", id);
+    const pk = this.pkOf(from);
+    const where = scopeWhere ? and(eq(pk, id), scopeWhere) : eq(pk, id);
     const { sql, params } = compileSelect({ from, where, limit: 1 }, this.dialect);
     return this.decodeRow(from, (await this.driver.exec(sql, params))[0] as Row | undefined);
   }
@@ -452,9 +471,10 @@ export class Db<S extends SchemaDef = SchemaDef> {
   private async finishRows(from: string, raw: Row[], scope: Scope, withSel: Selected): Promise<Row[]> {
     const relNames = withSel ? Object.keys(withSel).filter((k) => withSel[k]) : [];
     for (const relName of relNames) await this.loadRelation(from, raw, relName);
-    if (scope.fields === null) return raw; // base unrestricted -> no per-row narrowing possible
+    // Hidden columns are stripped even under an unrestricted/SYSTEM scope (never readable).
+    if (scope.fields === null) return raw.map((r) => this.stripHidden(from, r));
     return raw.map((r) => {
-      const projected = projectRow(r, effectiveFields(scope, r, this.acl.identity));
+      const projected = this.stripHidden(from, projectRow(r, effectiveFields(scope, r, this.acl.identity)));
       for (const relName of relNames) projected[relName] = r[relName]; // relations survive projection
       return projected;
     });
@@ -498,7 +518,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
       // parent[column] -> target.id
       const keys = [...new Set(rows.map((r) => r[rel.column]).filter((v) => v != null))];
       const byId = new Map<unknown, Row>();
-      for (const { key, row } of await fetchBy("id", keys)) byId.set(key, row);
+      for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys)) byId.set(key, row);
       for (const r of rows) r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
     } else {
       // hasMany: target[column] -> parent.id
@@ -545,16 +565,18 @@ export class Db<S extends SchemaDef = SchemaDef> {
    * would: the caller's readable fields for this row, PLUS the columns they just
    * wrote (which they already know) and the primary key (so a write-only caller
    * still gets the generated id). Full read access -> the whole row; SYSTEM -> as-is.
-   * This makes create/update echoes field-ACL-safe without ever collapsing to {}. */
+   * This makes create/update echoes field-ACL-safe without ever collapsing to {}.
+   * Hidden columns are never echoed, even when written or under SYSTEM. */
   private projectWrite(table: string, row: Row, writtenCols: string[]): Row {
-    if (this.acl.system) return row;
+    if (this.acl.system) return this.stripHidden(table, row);
     const visible = new Set<string>([this.pkOf(table), ...writtenCols]);
     const readScope = this.scopeFor(table, "read");
     if (readScope.allowed) {
       const readable = effectiveFields(readScope, row, this.acl.identity);
-      if (readable === null) return row; // unrestricted read -> echo everything
+      if (readable === null) return this.stripHidden(table, row); // unrestricted read -> echo everything (minus hidden)
       for (const f of readable) visible.add(f);
     }
+    for (const c of this.hiddenColsOf(table)) visible.delete(c);
     return projectRow(row, [...visible]);
   }
 
@@ -596,7 +618,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
       })
       .join(", ");
     params.push(this.dialect.encode(id));
-    let sql = `UPDATE ${this.dialect.id(table)} SET ${assignments} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(params.length)}`;
+    let sql = `UPDATE ${this.dialect.id(table)} SET ${assignments} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(params.length)}`;
     sql += this.scopeClause(scope.where, params);
     sql += this.returningClause("*");
     const updated = this.decodeRow(table, (await this.driver.exec(sql, params))[0]);
@@ -610,9 +632,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const scope = this.scopeFor(table, "delete");
     if (!scope.allowed) throw new AclDenied(table, "delete");
     const params: unknown[] = [this.dialect.encode(id)];
-    let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(1)}`;
+    let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(1)}`;
     sql += this.scopeClause(scope.where, params);
-    sql += this.returningClause("id");
+    sql += this.returningClause("*");
     return (await this.driver.exec(sql, params)).length > 0;
   }
 

package/src/sdk/schema.ts

@@ -39,6 +39,12 @@ export interface FieldDef {
    * rebuilds the table, copying data from the old column. A diff cannot tell a
    * rename from a drop+add, so the rename must be declared explicitly. */
   readonly renamedFrom?: string;
+  /** Never project this column on any ORM read — find/get, mutation echoes, relation
+   * loads, and the SYSTEM-mode admin data API all strip it, even under a full-access
+   * (allow()) or SYSTEM scope. Writable on insert/update, and still visible to raw
+   * `ctx.db.exec` (the escape hatch credential code uses). For secrets/internal
+   * columns like a password hash. Set by the `hidden()` modifier. */
+  readonly hidden?: boolean;
 }
 
 const builders = {
@@ -134,6 +140,14 @@ export function indexed<F extends FieldDef>(field: F): F & { readonly index: tru
   return { ...field, index: true };
 }
 
+/** Mark a column never-readable through the ORM: stripped from every read projection
+ * (find/get, mutation echoes, relation loads, admin data) even under full/SYSTEM
+ * access. Still writable, and still visible to raw `ctx.db.exec`. For secrets such as
+ * a password hash, e.g. `passwordHash: hidden(t.text())`. */
+export function hidden<F extends FieldDef>(field: F): F & { readonly hidden: true } {
+  return { ...field, hidden: true };
+}
+
 /** A raw-SQL column DEFAULT (emitted unquoted in the DDL), produced by the `expr`
  * helpers below. Distinct from a literal default so `defaultTo` can render
  * `DEFAULT datetime('now')` rather than the quoted string `DEFAULT 'datetime(...)'`. */