@pramen/server 0.0.1

package/dist/runtime/acl.d.ts

@@ -0,0 +1,62 @@
+import { type Action, type FieldsFn, type Identity, type PolicyRule, type ResolverDb, type Role, type Validator } from "../sdk/acl";
+import { type SqlExpr } from "./read-engine";
+import { PramenError } from "./errors";
+export declare class AclDenied extends PramenError {
+    readonly entity: string;
+    readonly action: Action;
+    readonly field?: string | undefined;
+    constructor(entity: string, action: Action, field?: string | undefined);
+}
+export interface CompiledAcl {
+    /** roleName -> entity\0action -> rules that grant it. */
+    readonly byRole: Map<string, Map<string, PolicyRule[]>>;
+}
+/** Per-request ACL context: the compiled policies plus the caller's identity. */
+export interface AclContext {
+    readonly acl: CompiledAcl;
+    readonly identity: Identity | null;
+    /** The request input (handler args), so policy `where` rules can reference an
+     * `$input(...)` marker — a capability / by-unguessable-key read grant. */
+    readonly input?: unknown;
+    /** Resolver results for this request (resolverId -> rule), from warmup(). */
+    readonly resolved?: Map<number, PolicyRule>;
+    /** SYSTEM mode bypasses all ACL — used for warmup reads and internal ops. */
+    readonly system?: boolean;
+}
+/** Evaluate every resolver reachable by the identity's roles, once per request.
+ * Resolvers read through a SYSTEM-mode db (ACL bypassed) to avoid recursion. */
+export declare function warmup(acl: CompiledAcl, identity: Identity | null, db: ResolverDb): Promise<Map<number, PolicyRule>>;
+export declare function compileAcl(roles: Role[]): CompiledAcl;
+/** A per-row additive field grant: `fields` apply to rows where `when` holds. */
+export interface ConditionalGrant {
+    readonly when: SqlExpr;
+    readonly fields: string[];
+}
+export interface Scope {
+    readonly allowed: boolean;
+    /** Row-level predicate to AND into the query. null = unrestricted. */
+    readonly where: SqlExpr | null;
+    /** Statically-granted base fields. null = all fields (no per-row narrowing). */
+    readonly fields: string[] | null;
+    /** Cell-level grants evaluated per row; additive over `fields`. */
+    readonly conditional: ConditionalGrant[];
+    /** Cell-level function resolvers evaluated per row; additive over `fields`. */
+    readonly fieldsFns: FieldsFn[];
+}
+export declare const ALLOW_ALL: Scope;
+export declare function resolveScope(ctx: AclContext, entity: string, action: Action): Scope;
+/** Effective visible fields for one row = base ∪ matching-conditional ∪ fn-output.
+ * Returns null (all fields) when the base is null or a resolver grants everything. */
+export declare function effectiveFields(scope: Scope, row: Record<string, unknown>, identity: Identity | null): string[] | null;
+/** Forced values + validators for a write, gathered from matched write policies.
+ * `set` values are resolved against the identity; later policies override earlier. */
+export interface WriteRules {
+    set: Record<string, unknown>;
+    validators: Validator[];
+}
+export declare function resolveWriteRules(ctx: AclContext, entity: string, action: Action): WriteRules;
+/** Scope for traversing `parentEntity.relName` to `target`. Grants come from the
+ * target's own read scope OR a parent read policy's relation rule with directAccess. */
+export declare function resolveRelationScope(ctx: AclContext, parentEntity: string, relName: string, target: string): Scope;
+/** Project a row to the permitted fields. null = all. */
+export declare function projectRow(row: Record<string, unknown>, fields: string[] | null): Record<string, unknown>;

package/dist/runtime/acl.js

@@ -0,0 +1,289 @@
+// ACL resolution — the runtime counterpart of sdk/acl.ts.
+// Given an identity + (entity, action), resolves a Scope: whether access is
+// granted, the row-level predicate to merge into the query, and any field
+// restriction. Deny-by-default; grants OR-merge across the identity's roles.
+import { deny, isAllow, isDeny, isIdentityMarker, isInputMarker, isResolver, } from "../sdk/acl";
+import { compileWhere, evalExpr, FALSE, or } from "./read-engine";
+import { PramenError } from "./errors";
+export class AclDenied extends PramenError {
+    entity;
+    action;
+    field;
+    constructor(entity, action, field) {
+        super(field ? `access denied: ${entity}.${field} (${action})` : `access denied: ${action} ${entity}`, 403, "forbidden");
+        this.entity = entity;
+        this.action = action;
+        this.field = field;
+        this.name = "AclDenied";
+    }
+}
+/** Evaluate every resolver reachable by the identity's roles, once per request.
+ * Resolvers read through a SYSTEM-mode db (ACL bypassed) to avoid recursion. */
+export async function warmup(acl, identity, db) {
+    const out = new Map();
+    for (const roleName of rolesOf(identity)) {
+        const byKey = acl.byRole.get(roleName);
+        if (!byKey)
+            continue;
+        for (const rules of byKey.values()) {
+            for (const rule of rules) {
+                if (!isResolver(rule) || out.has(rule.id))
+                    continue;
+                try {
+                    out.set(rule.id, await rule.fn({ identity, db }));
+                }
+                catch {
+                    out.set(rule.id, deny()); // a throwing resolver denies
+                }
+            }
+        }
+    }
+    return out;
+}
+const key = (entity, action) => `${entity}\0${action}`;
+export function compileAcl(roles) {
+    const byRole = new Map();
+    for (const r of roles) {
+        const byKey = byRole.get(r.name) ?? new Map();
+        for (const p of r.policies) {
+            const k = key(p.entity, p.action);
+            (byKey.get(k) ?? byKey.set(k, []).get(k)).push(p.rule);
+        }
+        byRole.set(r.name, byKey);
+    }
+    return { byRole };
+}
+export const ALLOW_ALL = { allowed: true, where: null, fields: null, conditional: [], fieldsFns: [] };
+const DENIED = { allowed: false, where: null, fields: null, conditional: [], fieldsFns: [] };
+/** Build a grant from a policy/relation rule, resolving $identity markers in
+ * `where` and each conditional `when`. */
+function grantOf(rule, where, identity, input) {
+    return {
+        where,
+        fields: rule.fields ?? null,
+        conditional: (rule.conditionalFields ?? []).map((cf) => ({
+            when: whereToExpr(cf.when, identity, input),
+            fields: cf.fields,
+        })),
+        fieldsFns: rule.fieldsFn ? [rule.fieldsFn] : [],
+    };
+}
+/** The roles to evaluate for a caller. An unauthenticated caller (no verified
+ * token) is treated as the `anonymous` role, so an app can grant first-class
+ * public reads/writes; if no `anonymous` role is defined this matches nothing
+ * (still deny-by-default). */
+function rolesOf(identity) {
+    if (!identity)
+        return ["anonymous"];
+    if (identity.roles?.length)
+        return identity.roles;
+    return identity.role ? [identity.role] : ["anonymous"];
+}
+function getPath(obj, path) {
+    return path.split(".").reduce((acc, seg) => (acc == null ? undefined : acc[seg]), obj ?? undefined);
+}
+const UNRESOLVED = Symbol("unresolved");
+// Resolve a value that may be an $identity marker (against the caller) or an
+// $input marker (against the request input — a capability/by-key grant). An
+// unresolvable marker yields UNRESOLVED, which makes its rule match nothing.
+function resolveValue(v, identity, input) {
+    if (isIdentityMarker(v)) {
+        const value = getPath(identity, v.path);
+        return value === undefined ? UNRESOLVED : value;
+    }
+    if (isInputMarker(v)) {
+        const value = getPath(input, v.path);
+        return value === undefined ? UNRESOLVED : value;
+    }
+    return v;
+}
+// Resolve every $identity marker in a policy where-rule (bare values, operator
+// objects, in/notIn arrays, AND/OR groups). Returns a plain WhereInput, or null
+// if any marker is unresolvable — in which case the rule matches nothing.
+function resolveMarkers(rule, identity, input) {
+    const out = {};
+    for (const [key, v] of Object.entries(rule)) {
+        if (key === "AND" || key === "OR") {
+            const groups = [];
+            for (const g of v) {
+                const resolved = resolveMarkers(g, identity, input);
+                if (resolved === null)
+                    return null;
+                groups.push(resolved);
+            }
+            out[key] = groups;
+            continue;
+        }
+        const isMarker = isIdentityMarker(v) || isInputMarker(v);
+        if (v !== null && typeof v === "object" && !isMarker && !Array.isArray(v)) {
+            const ops = {};
+            for (const [op, val] of Object.entries(v)) {
+                if (op === "in" || op === "notIn") {
+                    let arr;
+                    if (isIdentityMarker(val) || isInputMarker(val)) {
+                        arr = resolveValue(val, identity, input);
+                        if (arr === UNRESOLVED)
+                            return null;
+                    }
+                    else {
+                        const mapped = val.map((x) => resolveValue(x, identity, input));
+                        if (mapped.some((x) => x === UNRESOLVED))
+                            return null;
+                        arr = mapped;
+                    }
+                    if (!Array.isArray(arr))
+                        return null; // marker must resolve to a list
+                    ops[op] = arr;
+                }
+                else {
+                    const rv = resolveValue(val, identity, input);
+                    if (rv === UNRESOLVED)
+                        return null;
+                    ops[op] = rv;
+                }
+            }
+            out[key] = ops;
+        }
+        else {
+            const rv = resolveValue(v, identity, input);
+            if (rv === UNRESOLVED)
+                return null;
+            out[key] = rv;
+        }
+    }
+    return out;
+}
+/** Turn a policy where-rule into an expression. Supports the full user query
+ * surface (operators, AND/OR) with $identity / $input markers; an unresolvable
+ * marker makes the rule match nothing. */
+function whereToExpr(rule, identity, input) {
+    const resolved = resolveMarkers(rule, identity, input);
+    return resolved === null ? FALSE : compileWhere(resolved);
+}
+/** The concrete rules that apply for (entity, action) under this identity — with
+ * resolvers replaced by their warmup result and resolver/unresolved entries dropped. */
+function matchedRules(ctx, entity, action) {
+    const k = key(entity, action);
+    const out = [];
+    for (const roleName of rolesOf(ctx.identity)) {
+        const forRole = ctx.acl.byRole.get(roleName)?.get(k);
+        if (!forRole)
+            continue;
+        for (const raw of forRole) {
+            const rule = isResolver(raw) ? ctx.resolved?.get(raw.id) : raw;
+            if (rule && !isResolver(rule))
+                out.push(rule);
+        }
+    }
+    return out;
+}
+const ALLOW_GRANT = { where: null, fields: null, conditional: [], fieldsFns: [] };
+/** OR-merge a set of grants into a Scope. No grants -> denied. Conditional/function
+ * field grants concatenate; they only ADD fields to a non-null base. */
+function mergeGrants(grants) {
+    if (grants.length === 0)
+        return DENIED;
+    let unrestrictedWhere = false;
+    let unrestrictedFields = false;
+    const orParts = [];
+    const fields = new Set();
+    const conditional = [];
+    const fieldsFns = [];
+    for (const g of grants) {
+        if (g.where === null || g.where.t === "true")
+            unrestrictedWhere = true;
+        else
+            orParts.push(g.where);
+        if (g.fields === null)
+            unrestrictedFields = true;
+        else
+            for (const f of g.fields)
+                fields.add(f);
+        conditional.push(...g.conditional);
+        fieldsFns.push(...g.fieldsFns);
+    }
+    const where = unrestrictedWhere ? null : orParts.length === 1 ? orParts[0] : or(...orParts);
+    return {
+        allowed: true,
+        where,
+        fields: unrestrictedFields ? null : [...fields],
+        conditional,
+        fieldsFns,
+    };
+}
+export function resolveScope(ctx, entity, action) {
+    const grants = [];
+    for (const rule of matchedRules(ctx, entity, action)) {
+        if (isDeny(rule))
+            continue;
+        if (isAllow(rule))
+            grants.push(ALLOW_GRANT);
+        else
+            grants.push(grantOf(rule, whereToExpr(rule.where ?? {}, ctx.identity, ctx.input), ctx.identity, ctx.input));
+    }
+    return mergeGrants(grants);
+}
+/** Effective visible fields for one row = base ∪ matching-conditional ∪ fn-output.
+ * Returns null (all fields) when the base is null or a resolver grants everything. */
+export function effectiveFields(scope, row, identity) {
+    if (scope.fields === null)
+        return null;
+    const out = new Set(scope.fields);
+    for (const g of scope.conditional)
+        if (evalExpr(g.when, row))
+            for (const f of g.fields)
+                out.add(f);
+    for (const fn of scope.fieldsFns) {
+        const extra = fn(identity, row);
+        if (extra === null)
+            return null;
+        for (const f of extra)
+            out.add(f);
+    }
+    return [...out];
+}
+export function resolveWriteRules(ctx, entity, action) {
+    const set = {};
+    const validators = [];
+    for (const rule of matchedRules(ctx, entity, action)) {
+        if (isAllow(rule) || isDeny(rule))
+            continue;
+        if (rule.set) {
+            for (const [col, v] of Object.entries(rule.set)) {
+                set[col] = typeof v === "function" ? v(ctx.identity) : v;
+            }
+        }
+        if (rule.validate)
+            validators.push(rule.validate);
+    }
+    return { set, validators };
+}
+/** Scope for traversing `parentEntity.relName` to `target`. Grants come from the
+ * target's own read scope OR a parent read policy's relation rule with directAccess. */
+export function resolveRelationScope(ctx, parentEntity, relName, target) {
+    if (ctx.system)
+        return ALLOW_ALL;
+    const grants = [];
+    const base = resolveScope(ctx, target, "read");
+    if (base.allowed)
+        grants.push({ where: base.where, fields: base.fields, conditional: base.conditional, fieldsFns: base.fieldsFns });
+    for (const rule of matchedRules(ctx, parentEntity, "read")) {
+        if (isAllow(rule) || isDeny(rule))
+            continue;
+        const rel = rule.relations?.[relName];
+        if (rel?.directAccess) {
+            grants.push(grantOf(rel, rel.where ? whereToExpr(rel.where, ctx.identity, ctx.input) : null, ctx.identity, ctx.input));
+        }
+    }
+    return mergeGrants(grants);
+}
+/** Project a row to the permitted fields. null = all. */
+export function projectRow(row, fields) {
+    if (!fields)
+        return row;
+    const out = {};
+    for (const f of fields)
+        if (f in row)
+            out[f] = row[f];
+    return out;
+}

package/dist/runtime/db.d.ts

@@ -0,0 +1,139 @@
+import { type AclContext } from "./acl";
+import { type AggFn } from "./read-engine";
+import type { Driver } from "./driver";
+import type { EntityFields, SchemaDef } from "../sdk/schema";
+import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereInput } from "../sdk/infer";
+type Row = Record<string, unknown>;
+type Id = string | number | bigint;
+type OrderSpec<S extends SchemaDef, T extends keyof S> = {
+    column: keyof FieldsOf<S[T]> & string;
+    dir?: "asc" | "desc";
+};
+export interface FindSpec<S extends SchemaDef, T extends keyof S> {
+    from: T;
+    where?: WhereInput<FieldsOf<S[T]>>;
+    orderBy?: OrderSpec<S, T> | OrderSpec<S, T>[];
+    limit?: number;
+    offset?: number;
+    /** Eager-load relations. Each loaded relation is independently ACL-checked. */
+    with?: Partial<Record<keyof RelationsOf<S[T]> & string, true>>;
+}
+/** Cursor (keyset) pagination input — `after` is an opaque cursor from a prior page. */
+export interface PageSpec<S extends SchemaDef, T extends keyof S> {
+    from: T;
+    where?: WhereInput<FieldsOf<S[T]>>;
+    orderBy?: OrderSpec<S, T> | OrderSpec<S, T>[];
+    limit?: number;
+    after?: string;
+    with?: Partial<Record<keyof RelationsOf<S[T]> & string, true>>;
+}
+export interface Page<R> {
+    items: R[];
+    /** Opaque cursor for the last item — pass as `after` to fetch the next page. */
+    cursor: string | null;
+    hasMore: boolean;
+}
+/** The aggregations map of an aggregate spec, keyed by output column name. */
+type Aggregations<F extends EntityFields> = Record<string, {
+    fn: AggFn;
+    column?: keyof F & string;
+}>;
+export interface AggregateSpec<S extends SchemaDef, T extends keyof S> {
+    from: T;
+    where?: WhereInput<FieldsOf<S[T]>>;
+    groupBy?: (keyof FieldsOf<S[T]> & string) | (keyof FieldsOf<S[T]> & string)[];
+    aggregations: Aggregations<FieldsOf<S[T]>>;
+}
+/** One aggregate result row: loosely typed (any output column -> value). */
+export type AggregateRow = Record<string, number | string | null>;
+type GroupKeys<G> = G extends readonly (infer K)[] ? K : G;
+/** The value type of a single aggregation: count -> number; min/max -> the column's
+ * own type (nullable); sum/avg -> number | null. */
+type AggValue<Fn extends AggFn, Col, F extends EntityFields> = Fn extends "count" ? number : Fn extends "min" | "max" ? Col extends keyof F ? Cell<F[Col]> | null : number | null : number | null;
+/** A result row inferred from a (groupBy, aggregations) spec: group columns keep
+ * their schema type, each aggregation gets its computed value type. */
+export type AggregateResult<F extends EntityFields, G, A extends Aggregations<F>> = {
+    [K in Extract<GroupKeys<G>, keyof F & string>]: Cell<F[K]>;
+} & {
+    [K in keyof A]: AggValue<A[K]["fn"], A[K]["column"], F>;
+};
+export declare class Db<S extends SchemaDef = SchemaDef> {
+    private readonly driver;
+    private readonly acl;
+    private readonly schema;
+    /** Tables read or written during this Db's lifetime. */
+    readonly touched: Set<string>;
+    private readonly dialect;
+    constructor(driver: Driver, acl: AclContext, schema: SchemaDef);
+    /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
+    private scopeFor;
+    /** Forced `set` values + validators for a write (empty in SYSTEM mode). The two
+     * halves are applied separately so the cell-level field check can run AFTER `set`
+     * (so a conditional `when` sees forced columns) but BEFORE `validate`. */
+    private writeRules;
+    /** Run write validators against the final values; a throw surfaces as a 400. */
+    private runValidators;
+    /** Enforce field-level (incl. cell-level) write permission for one row. `setCols`
+     * are server-forced values that bypass the restriction. `evalRow` is the row the
+     * per-row grants are evaluated against (candidate on insert, post-merge on update). */
+    private checkWriteFields;
+    /** Reject ordering by a column the caller cannot read (closes an info-leak: order
+     * and the keyset cursor would otherwise expose a hidden column's values). Columns
+     * granted only conditionally are NOT orderable. */
+    private assertReadableCols;
+    /** Structured read; ACL row-scope is AND-ed in, permitted fields projected.
+     * Selected relations are eager-loaded, each independently ACL-checked. */
+    find<T extends keyof S & string>(spec: FindSpec<S, T>): Promise<(InferRow<FieldsOf<S[T]>> & RelationsResult<S, T>)[]>;
+    /** Cursor (keyset) pagination. Stable under inserts/deletes; the PK is appended
+     * to `orderBy` as a tiebreaker so the keyset is unique. Returns the page plus an
+     * opaque `cursor` (pass back as `after`) and whether more rows remain. */
+    page<T extends keyof S & string>(spec: PageSpec<S, T>): Promise<Page<InferRow<FieldsOf<S[T]>> & RelationsResult<S, T>>>;
+    /** Count rows visible to the caller (ACL read scope applied). */
+    count<T extends keyof S & string>(spec: {
+        from: T;
+        where?: WhereInput<FieldsOf<S[T]>>;
+    }): Promise<number>;
+    /** Grouped aggregation (count/sum/avg/min/max). ACL read scope is applied, and
+     * every referenced column must be readable under field permissions. The result
+     * row type is inferred from the spec: group columns keep their schema type and
+     * each aggregation gets its computed value type. */
+    aggregate<T extends keyof S & string, A extends Aggregations<FieldsOf<S[T]>>, G extends (keyof FieldsOf<S[T]> & string) | (keyof FieldsOf<S[T]> & string)[] = never>(spec: {
+        from: T;
+        where?: WhereInput<FieldsOf<S[T]>>;
+        groupBy?: G;
+        aggregations: A;
+    }): Promise<AggregateResult<FieldsOf<S[T]>, G, A>[]>;
+    private readWhere;
+    private selectRaw;
+    private jsonColsOf;
+    private decodeRows;
+    private decodeRow;
+    /** Encode one write cell: JSON-stringify a json/fileRef value, then dialect-encode. */
+    private encodeCell;
+    /** Fetch one row by id within an ACL row-scope (for per-row write evaluation). */
+    private fetchOne;
+    private finishRows;
+    private orderWithPk;
+    private pkOf;
+    /** Eager-load one relation onto `rows` (mutates them). Traversal is ACL-checked
+     * via resolveRelationScope: the related read scope OR a parent directAccess grant. */
+    private loadRelation;
+    /** Insert a single row, returning the persisted row. */
+    insert<T extends keyof S & string>(table: T, values: InferInsert<FieldsOf<S[T]>>): Promise<InferRow<FieldsOf<S[T]>>>;
+    /** Project a mutation's RETURNING row so the echo never reveals more than a read
+     * 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 {}. */
+    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. */
+    update<T extends keyof S & string>(table: T, id: Id, patch: InferUpdate<FieldsOf<S[T]>>): Promise<InferRow<FieldsOf<S[T]>> | undefined>;
+    /** Delete a row by id within scope. Returns whether a row was deleted. */
+    delete<T extends keyof S & string>(table: T, id: Id): Promise<boolean>;
+    /** Escape hatch — raw SQL, NOT ACL-checked. For system/internal use only. */
+    exec(sql: string, ...params: unknown[]): Promise<Row[]>;
+    private returningClause;
+    private scopeClause;
+}
+export {};