@lunora/server 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/types.d-BDY0FYHK.d.ts

@@ -0,0 +1,135 @@
+import { WhereOf } from "../data-model.js";
+/** Structural mirror of `@lunora/do`'s `WhereInput`. */
+interface WhereInput {
+  [field: string]: unknown;
+  AND?: WhereInput[];
+  NOT?: WhereInput;
+  OR?: WhereInput[];
+}
+/** Operations a policy can gate. `read` covers `get`/`findMany`/`query`/`count`. */
+type PolicyOperation = "delete" | "insert" | "read" | "update";
+/**
+* A policy's `when` decision:
+*
+* - `WhereInput`: a row-shape predicate. On reads it is AND-merged into every
+* query against the table — the row is invisible unless it matches. On writes
+* it is evaluated against the candidate document (`insert`) or the pre-write
+* row (`update`/`delete`); a mismatch denies the write with
+* `LunoraError("FORBIDDEN")`. Same operator set as the SQL compiler
+* (`eq`/`ne`/`in`/`notIn`/`lt`/`lte`/`gt`/`gte`/`isNull`/`contains` +
+* `AND`/`OR`/`NOT`).
+* - `true`: unrestricted. On reads no predicate is merged; on writes the row is
+* allowed.
+* - `false`: deny. On reads the table is forced to match zero rows (a sentinel
+* predicate); on writes the operation throws `LunoraError("FORBIDDEN")`.
+*
+* Returning `undefined` opts this specific policy out (rare; useful when
+* branching on `ctx.auth.roles`).
+*/
+type PolicyDecision = WhereInput | boolean | undefined;
+/**
+* Relation-aware twin of {@link PolicyDecision}, parameterized over the
+* generated `DataModel` (`DM`) + `Relations` (`REL`) maps and a table `T`. A
+* read policy may now return a Prisma-style relation predicate (the
+* `@lunora/do` pre-resolver resolves it via a semijoin), so the typed
+* authoring surface accepts `WhereOf<DM, REL, T>` — column predicates **and**
+* `is`/`isNot`/`some`/`none`/`every` over `T`'s declared relations — in
+* addition to the `boolean`/`undefined` decisions. Used by the project-bound
+* `definePolicy` from `createPolicyDsl`.
+*/
+type PolicyDecisionOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = WhereOf<DM, REL, T> | boolean | undefined;
+/**
+* Relation-aware input for a project-bound `definePolicy` (see
+* `createPolicyDsl`). `table` is constrained to a real table name and
+* `when`'s return type is the table-specific {@link PolicyDecisionOf} — so an
+* unknown table, a stray column, or a relation predicate naming a relation the
+* table does not declare is a compile error rather than a silent runtime deny.
+*/
+interface TypedDefinePolicyInput<DM, REL extends Record<keyof DM, object>, T extends keyof DM, Context = unknown> {
+  on: PolicyOperation;
+  table: T;
+  when: (context: PolicyContext<Context>) => PolicyDecisionOf<DM, REL, T>;
+}
+/**
+* Context handed to a policy. `auth.roles` is the per-request role list,
+* sourced from the identity resolver (better-auth claims today). `auth.can`
+* answers whether any of those roles grants a permission (see
+* {@link Permission} / {@link RlsOptions}). `row` is present only on write
+* policies (`insert`/`update`/`delete`) — for `update` and `delete` it is the
+* pre-write row; for `insert` it is the candidate document. `ctx` is the full
+* procedure context the middleware closed over.
+*/
+interface PolicyContext<Context = unknown> {
+  readonly auth: {
+    /**
+    * `true` when any of the request's `roles` grants `permission` (passed
+    * by {@link Permission} object or its `name`). Always `false` when no
+    * roles were handed to the middleware (`rls(policies, { roles })`), or
+    * when none of the request's roles lists the permission.
+    */
+    readonly can: (permission: Permission | string) => boolean;
+    readonly identity?: Record<string, unknown> | null;
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
+  };
+  readonly ctx: Context;
+  readonly row?: Record<string, unknown>;
+}
+/** A registered policy as stored in the policy table. */
+interface Policy<Context = unknown> {
+  readonly on: PolicyOperation;
+  readonly table: string;
+  readonly when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+* Input accepted by `definePolicy`. The branded result is the same
+* shape; we keep the input/output split so callers can read JSDoc on the
+* constructor without the type re-exposing `Policy` internals.
+*/
+interface DefinePolicyInput<Context = unknown> {
+  on: PolicyOperation;
+  /** Logical table name the policy applies to. */
+  table: string;
+  /**
+  * Decision function. Returning a `WhereInput` (read only) AND-merges the
+  * predicate; `true` allows; `false` denies; `undefined` skips this policy.
+  *
+  * NOTE: `count()` is **unsupported** on a policy-restricted table — the
+  * reader throws `LunoraError("COUNT_RLS_UNSUPPORTED")` (422). This mirrors
+  * kitcn's documented behavior.
+  */
+  when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+* A named, abstract capability a policy can check with `ctx.auth.can(...)`,
+* instead of branching on raw role strings. Declare one with
+* `definePermission`; grant it to a role via {@link Role.permissions};
+* register the roles with the middleware via {@link RlsOptions.roles}.
+*/
+interface Permission {
+  readonly description?: string;
+  readonly name: string;
+}
+/**
+* A role declaration. Roles are string labels attached to the request's
+* identity (via better-auth claims today). `permissions` lists the
+* capabilities the role grants — at request time the middleware unions the
+* permissions of every role in `ctx.auth.roles` so a policy can ask
+* `ctx.auth.can(permission)` rather than enumerate roles.
+*/
+interface Role {
+  readonly description?: string;
+  readonly name: string;
+  /** Permissions this role grants — by {@link Permission} object or bare name. */
+  readonly permissions?: ReadonlyArray<Permission | string>;
+}
+/**
+* Options for the `rls(policies, options)` middleware. `roles` registers the
+* role→permission grants that back `ctx.auth.can(...)`; a role not listed here
+* grants no permissions (so `can` is conservative — it fails closed for
+* unknown roles).
+*/
+interface RlsOptions {
+  readonly roles?: ReadonlyArray<Role>;
+}
+export { DefinePolicyInput as D, PolicyOperation as P, Role as R, TypedDefinePolicyInput as T, WhereInput as W, Policy as a, Permission as b, RlsOptions as c, PolicyContext as d, PolicyDecision as e, PolicyDecisionOf as f };

package/dist/packem_shared/types.d-DmvyEMD6.d.mts

@@ -0,0 +1,135 @@
+import { WhereOf } from "../data-model.mjs";
+/** Structural mirror of `@lunora/do`'s `WhereInput`. */
+interface WhereInput {
+  [field: string]: unknown;
+  AND?: WhereInput[];
+  NOT?: WhereInput;
+  OR?: WhereInput[];
+}
+/** Operations a policy can gate. `read` covers `get`/`findMany`/`query`/`count`. */
+type PolicyOperation = "delete" | "insert" | "read" | "update";
+/**
+* A policy's `when` decision:
+*
+* - `WhereInput`: a row-shape predicate. On reads it is AND-merged into every
+* query against the table — the row is invisible unless it matches. On writes
+* it is evaluated against the candidate document (`insert`) or the pre-write
+* row (`update`/`delete`); a mismatch denies the write with
+* `LunoraError("FORBIDDEN")`. Same operator set as the SQL compiler
+* (`eq`/`ne`/`in`/`notIn`/`lt`/`lte`/`gt`/`gte`/`isNull`/`contains` +
+* `AND`/`OR`/`NOT`).
+* - `true`: unrestricted. On reads no predicate is merged; on writes the row is
+* allowed.
+* - `false`: deny. On reads the table is forced to match zero rows (a sentinel
+* predicate); on writes the operation throws `LunoraError("FORBIDDEN")`.
+*
+* Returning `undefined` opts this specific policy out (rare; useful when
+* branching on `ctx.auth.roles`).
+*/
+type PolicyDecision = WhereInput | boolean | undefined;
+/**
+* Relation-aware twin of {@link PolicyDecision}, parameterized over the
+* generated `DataModel` (`DM`) + `Relations` (`REL`) maps and a table `T`. A
+* read policy may now return a Prisma-style relation predicate (the
+* `@lunora/do` pre-resolver resolves it via a semijoin), so the typed
+* authoring surface accepts `WhereOf<DM, REL, T>` — column predicates **and**
+* `is`/`isNot`/`some`/`none`/`every` over `T`'s declared relations — in
+* addition to the `boolean`/`undefined` decisions. Used by the project-bound
+* `definePolicy` from `createPolicyDsl`.
+*/
+type PolicyDecisionOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = WhereOf<DM, REL, T> | boolean | undefined;
+/**
+* Relation-aware input for a project-bound `definePolicy` (see
+* `createPolicyDsl`). `table` is constrained to a real table name and
+* `when`'s return type is the table-specific {@link PolicyDecisionOf} — so an
+* unknown table, a stray column, or a relation predicate naming a relation the
+* table does not declare is a compile error rather than a silent runtime deny.
+*/
+interface TypedDefinePolicyInput<DM, REL extends Record<keyof DM, object>, T extends keyof DM, Context = unknown> {
+  on: PolicyOperation;
+  table: T;
+  when: (context: PolicyContext<Context>) => PolicyDecisionOf<DM, REL, T>;
+}
+/**
+* Context handed to a policy. `auth.roles` is the per-request role list,
+* sourced from the identity resolver (better-auth claims today). `auth.can`
+* answers whether any of those roles grants a permission (see
+* {@link Permission} / {@link RlsOptions}). `row` is present only on write
+* policies (`insert`/`update`/`delete`) — for `update` and `delete` it is the
+* pre-write row; for `insert` it is the candidate document. `ctx` is the full
+* procedure context the middleware closed over.
+*/
+interface PolicyContext<Context = unknown> {
+  readonly auth: {
+    /**
+    * `true` when any of the request's `roles` grants `permission` (passed
+    * by {@link Permission} object or its `name`). Always `false` when no
+    * roles were handed to the middleware (`rls(policies, { roles })`), or
+    * when none of the request's roles lists the permission.
+    */
+    readonly can: (permission: Permission | string) => boolean;
+    readonly identity?: Record<string, unknown> | null;
+    readonly roles: ReadonlyArray<string>;
+    readonly userId: null | string;
+  };
+  readonly ctx: Context;
+  readonly row?: Record<string, unknown>;
+}
+/** A registered policy as stored in the policy table. */
+interface Policy<Context = unknown> {
+  readonly on: PolicyOperation;
+  readonly table: string;
+  readonly when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+* Input accepted by `definePolicy`. The branded result is the same
+* shape; we keep the input/output split so callers can read JSDoc on the
+* constructor without the type re-exposing `Policy` internals.
+*/
+interface DefinePolicyInput<Context = unknown> {
+  on: PolicyOperation;
+  /** Logical table name the policy applies to. */
+  table: string;
+  /**
+  * Decision function. Returning a `WhereInput` (read only) AND-merges the
+  * predicate; `true` allows; `false` denies; `undefined` skips this policy.
+  *
+  * NOTE: `count()` is **unsupported** on a policy-restricted table — the
+  * reader throws `LunoraError("COUNT_RLS_UNSUPPORTED")` (422). This mirrors
+  * kitcn's documented behavior.
+  */
+  when: (context: PolicyContext<Context>) => PolicyDecision;
+}
+/**
+* A named, abstract capability a policy can check with `ctx.auth.can(...)`,
+* instead of branching on raw role strings. Declare one with
+* `definePermission`; grant it to a role via {@link Role.permissions};
+* register the roles with the middleware via {@link RlsOptions.roles}.
+*/
+interface Permission {
+  readonly description?: string;
+  readonly name: string;
+}
+/**
+* A role declaration. Roles are string labels attached to the request's
+* identity (via better-auth claims today). `permissions` lists the
+* capabilities the role grants — at request time the middleware unions the
+* permissions of every role in `ctx.auth.roles` so a policy can ask
+* `ctx.auth.can(permission)` rather than enumerate roles.
+*/
+interface Role {
+  readonly description?: string;
+  readonly name: string;
+  /** Permissions this role grants — by {@link Permission} object or bare name. */
+  readonly permissions?: ReadonlyArray<Permission | string>;
+}
+/**
+* Options for the `rls(policies, options)` middleware. `roles` registers the
+* role→permission grants that back `ctx.auth.can(...)`; a role not listed here
+* grants no permissions (so `can` is conservative — it fails closed for
+* unknown roles).
+*/
+interface RlsOptions {
+  readonly roles?: ReadonlyArray<Role>;
+}
+export { DefinePolicyInput as D, PolicyOperation as P, Role as R, TypedDefinePolicyInput as T, WhereInput as W, Policy as a, Permission as b, RlsOptions as c, PolicyContext as d, PolicyDecision as e, PolicyDecisionOf as f };

package/dist/rls/testing.d.mts

@@ -0,0 +1,63 @@
+import { P as PolicyOperation, R as Role, a as Policy } from "../packem_shared/types.d-DmvyEMD6.mjs";
+import "../data-model.mjs";
+/**
+* The slice of a request identity a policy reads. Mirrors the
+* `PolicyContext.auth` shape the middleware builds at request time — every
+* field is optional and defaults the same way the middleware defaults it
+* (`userId`/`identity` → `null`, `roles` → `[]`).
+*/
+interface TestIdentity {
+  /** Raw identity claims a policy may branch on (`auth.identity.email`, …). */
+  identity?: Record<string, unknown> | null;
+  /** Role labels the request carries; resolved to permissions via the harness `roles` registry. */
+  roles?: ReadonlyArray<string>;
+  /** The caller id (`auth.userId`); `null`/omitted is the anonymous caller. */
+  userId?: null | string;
+}
+/** Options for {@link expectPolicy}. */
+interface ExpectPolicyOptions<Context = unknown> {
+  /**
+  * The procedure context a policy reads via `ctx` (e.g. `ctx.orgId`). Held
+  * for the whole harness; pass a fresh `expectPolicy(..., { ctx })` for a
+  * different context. Defaults to an empty object.
+  */
+  ctx?: Context;
+  /**
+  * Role→permission grants backing `auth.can(...)` — the same registry passed
+  * to `rls(policies, { roles })`. A role not listed here grants nothing, so
+  * `can(...)` fails closed exactly as it does in production.
+  */
+  roles?: ReadonlyArray<Role>;
+}
+/** A harness bound to one identity; answers can/cannot for an `(op, table, row)`. */
+interface BoundPolicyAssertion {
+  /**
+  * Would this identity be **allowed** the operation on `row`?
+  *
+  * - `read` — is `row` visible? `true` when the table has no read policy (unrestricted), or when the effective read `baseWhere` matches `row`.
+  * - `insert` — is the candidate `row` allowed by the insert policies?
+  * - `update` / `delete` — is the pre-write `row` allowed? For `update` pass `nextRow` to also assert the post-image (WITH CHECK) — a policy can't be satisfied by the old row while the patch reassigns it to another tenant.
+  *
+  * A table with **no** policy in the list is unguarded → always `true`
+  * (mirrors the middleware passing such tables through unwrapped). A table
+  * that participates but declares no policy for the write `op` denies
+  * (default-DENY), exactly as the middleware does.
+  */
+  can: (op: PolicyOperation, table: string, row?: Record<string, unknown>, nextRow?: Record<string, unknown>) => boolean;
+  /** Negation of {@link BoundPolicyAssertion.can} — reads more naturally in a denial test. */
+  cannot: (op: PolicyOperation, table: string, row?: Record<string, unknown>, nextRow?: Record<string, unknown>) => boolean;
+}
+/** A harness over a policy set; `.as(identity)` binds an identity to assert against. */
+interface PolicyAssertion {
+  /** Bind an identity (or `null`/omitted for the anonymous caller) and assert against it. */
+  as: (identity?: TestIdentity | null) => BoundPolicyAssertion;
+}
+/**
+* Build an in-process assertion harness over a policy set. Reuses the `rls()`
+* middleware's own evaluation primitives, so an assertion is faithful to
+* request-time behaviour by construction.
+* @param policies the policy list, typically from `definePolicies([...])`.
+* @param options role registry + procedure `ctx` (see {@link ExpectPolicyOptions}).
+*/
+declare const expectPolicy: <Context = unknown>(policies: ReadonlyArray<Policy<Context>>, options?: ExpectPolicyOptions<Context>) => PolicyAssertion;
+export { BoundPolicyAssertion, ExpectPolicyOptions, PolicyAssertion, TestIdentity, expectPolicy };

package/dist/rls/testing.d.ts

@@ -0,0 +1,63 @@
+import { P as PolicyOperation, R as Role, a as Policy } from "../packem_shared/types.d-BDY0FYHK.js";
+import "../data-model.js";
+/**
+* The slice of a request identity a policy reads. Mirrors the
+* `PolicyContext.auth` shape the middleware builds at request time — every
+* field is optional and defaults the same way the middleware defaults it
+* (`userId`/`identity` → `null`, `roles` → `[]`).
+*/
+interface TestIdentity {
+  /** Raw identity claims a policy may branch on (`auth.identity.email`, …). */
+  identity?: Record<string, unknown> | null;
+  /** Role labels the request carries; resolved to permissions via the harness `roles` registry. */
+  roles?: ReadonlyArray<string>;
+  /** The caller id (`auth.userId`); `null`/omitted is the anonymous caller. */
+  userId?: null | string;
+}
+/** Options for {@link expectPolicy}. */
+interface ExpectPolicyOptions<Context = unknown> {
+  /**
+  * The procedure context a policy reads via `ctx` (e.g. `ctx.orgId`). Held
+  * for the whole harness; pass a fresh `expectPolicy(..., { ctx })` for a
+  * different context. Defaults to an empty object.
+  */
+  ctx?: Context;
+  /**
+  * Role→permission grants backing `auth.can(...)` — the same registry passed
+  * to `rls(policies, { roles })`. A role not listed here grants nothing, so
+  * `can(...)` fails closed exactly as it does in production.
+  */
+  roles?: ReadonlyArray<Role>;
+}
+/** A harness bound to one identity; answers can/cannot for an `(op, table, row)`. */
+interface BoundPolicyAssertion {
+  /**
+  * Would this identity be **allowed** the operation on `row`?
+  *
+  * - `read` — is `row` visible? `true` when the table has no read policy (unrestricted), or when the effective read `baseWhere` matches `row`.
+  * - `insert` — is the candidate `row` allowed by the insert policies?
+  * - `update` / `delete` — is the pre-write `row` allowed? For `update` pass `nextRow` to also assert the post-image (WITH CHECK) — a policy can't be satisfied by the old row while the patch reassigns it to another tenant.
+  *
+  * A table with **no** policy in the list is unguarded → always `true`
+  * (mirrors the middleware passing such tables through unwrapped). A table
+  * that participates but declares no policy for the write `op` denies
+  * (default-DENY), exactly as the middleware does.
+  */
+  can: (op: PolicyOperation, table: string, row?: Record<string, unknown>, nextRow?: Record<string, unknown>) => boolean;
+  /** Negation of {@link BoundPolicyAssertion.can} — reads more naturally in a denial test. */
+  cannot: (op: PolicyOperation, table: string, row?: Record<string, unknown>, nextRow?: Record<string, unknown>) => boolean;
+}
+/** A harness over a policy set; `.as(identity)` binds an identity to assert against. */
+interface PolicyAssertion {
+  /** Bind an identity (or `null`/omitted for the anonymous caller) and assert against it. */
+  as: (identity?: TestIdentity | null) => BoundPolicyAssertion;
+}
+/**
+* Build an in-process assertion harness over a policy set. Reuses the `rls()`
+* middleware's own evaluation primitives, so an assertion is faithful to
+* request-time behaviour by construction.
+* @param policies the policy list, typically from `definePolicies([...])`.
+* @param options role registry + procedure `ctx` (see {@link ExpectPolicyOptions}).
+*/
+declare const expectPolicy: <Context = unknown>(policies: ReadonlyArray<Policy<Context>>, options?: ExpectPolicyOptions<Context>) => PolicyAssertion;
+export { BoundPolicyAssertion, ExpectPolicyOptions, PolicyAssertion, TestIdentity, expectPolicy };

package/dist/rls/testing.mjs

@@ -0,0 +1,49 @@
+import { indexRolePermissions, computeReadBaseWhere, matchesWhere, evaluateWrite, permissionName } from '../packem_shared/rls-2Jhd0uev.mjs';
+
+const expectPolicy = (policies, options = {}) => {
+  const rolePermissions = indexRolePermissions(options.roles);
+  const context = options.ctx ?? {};
+  return {
+    as: (identity) => {
+      const auth = identity ?? {};
+      const roles = auth.roles ?? [];
+      const granted = /* @__PURE__ */ new Set();
+      for (const roleName of roles) {
+        for (const name of rolePermissions.get(roleName) ?? []) {
+          granted.add(name);
+        }
+      }
+      const baseContext = {
+        auth: {
+          can: (permission) => granted.has(permissionName(permission)),
+          // eslint-disable-next-line unicorn/no-null -- PolicyContext.auth.identity is a public `… | null` type, mirroring the middleware
+          identity: auth.identity ?? null,
+          roles,
+          // eslint-disable-next-line unicorn/no-null -- PolicyContext.auth.userId is a public `null | string` type, mirroring the middleware
+          userId: auth.userId ?? null
+        },
+        ctx: context
+      };
+      const can = (op, table, row, nextRow) => {
+        const tablePolicies = policies.filter((policy) => policy.table === table);
+        if (tablePolicies.length === 0) {
+          return true;
+        }
+        if (op === "read") {
+          if (!tablePolicies.some((policy) => policy.on === "read")) {
+            return true;
+          }
+          const baseWhere = computeReadBaseWhere(tablePolicies, baseContext);
+          return baseWhere === void 0 || matchesWhere(row ?? {}, baseWhere);
+        }
+        return evaluateWrite(tablePolicies, op, { ...baseContext, row }, nextRow);
+      };
+      return {
+        can,
+        cannot: (op, table, row, nextRow) => !can(op, table, row, nextRow)
+      };
+    }
+  };
+};
+
+export { expectPolicy };