@pramen/server 0.0.46 → 0.0.47

package/dist/index.d.ts

@@ -5,8 +5,8 @@ export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, Schema
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
 export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
-export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
-export type { Action, Identity, IdentityMarker, InputMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
+export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker, isNowMarker } from "./sdk/acl";
+export type { Action, Identity, IdentityMarker, InputMarker, NowMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
 export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";
 export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";

package/dist/index.js

@@ -13,7 +13,7 @@ export { isValidUuid } from "./sdk/uuid";
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
 // --- ACL ---
-export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
+export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker, isNowMarker } from "./sdk/acl";
 // --- kv (ctx.kv) + session denylist (hard token revocation) ---
 export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";

package/dist/runtime/acl.d.ts

@@ -63,7 +63,7 @@ export declare const ALLOW_ALL: Scope;
 export declare const MAX_REL_DEPTH = 5;
 /** Compile a where-rule (user query or policy) into a SqlExpr. Plain columns go
  * through the marker-resolving compiler; relation keys (`{ rel: { … } }`) become
- * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input
+ * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input/$now
  * markers; an unresolvable marker makes its branch match nothing. Schema-less
  * contexts (no relations) behave exactly like the flat compiler.
  *

package/dist/runtime/acl.js

@@ -2,7 +2,7 @@
 // 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 { deny, isAllow, isDeny, isIdentityMarker, isInputMarker, isNowMarker, isResolver, } from "../sdk/acl";
 import { and, compileWhere, evalExpr, FALSE, not, or, TRUE } from "./read-engine";
 import { BadRequest, PramenError } from "./errors";
 export class AclDenied extends PramenError {
@@ -85,10 +85,13 @@ 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.
+// Resolve a value that may be an $identity marker (against the caller), an
+// $input marker (against the request input — a capability/by-key grant), or a
+// $now marker (the evaluation instant). An unresolvable marker yields UNRESOLVED,
+// which makes its rule match nothing. $now always resolves.
 function resolveValue(v, identity, input) {
+    if (isNowMarker(v))
+        return new Date().toISOString();
     if (isIdentityMarker(v)) {
         const value = getPath(identity, v.path);
         return value === undefined ? UNRESOLVED : value;
@@ -99,7 +102,7 @@ function resolveValue(v, identity, input) {
     }
     return v;
 }
-// Resolve every $identity/$input marker in a SINGLE level of a where-rule (bare
+// Resolve every $identity/$input/$now marker in a SINGLE level of a where-rule (bare
 // values, operator objects, in/notIn arrays). AND/OR groups are split off by
 // `compileScopedWhere` before this runs, so this only ever sees plain columns.
 // Returns a plain WhereInput, or null if any marker is unresolvable — in which
@@ -111,7 +114,7 @@ function resolveValue(v, identity, input) {
 function resolveMarkers(rule, identity, input) {
     const out = {};
     for (const [key, v] of Object.entries(rule)) {
-        const isMarker = isIdentityMarker(v) || isInputMarker(v);
+        const isMarker = isIdentityMarker(v) || isInputMarker(v) || isNowMarker(v);
         if (v !== null && typeof v === "object" && !isMarker && !Array.isArray(v)) {
             const ops = {};
             for (const [op, val] of Object.entries(v)) {
@@ -241,7 +244,7 @@ function relationPredicate(rel, nested, parentEntity, ctx, depth) {
 }
 /** Compile a where-rule (user query or policy) into a SqlExpr. Plain columns go
  * through the marker-resolving compiler; relation keys (`{ rel: { … } }`) become
- * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input
+ * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input/$now
  * markers; an unresolvable marker makes its branch match nothing. Schema-less
  * contexts (no relations) behave exactly like the flat compiler.
  *

package/dist/sdk/acl.d.ts

@@ -29,6 +29,27 @@ export interface InputMarker {
  * to enumerate. An absent input value makes the rule match nothing (safe deny). */
 export declare function $input(path: string): InputMarker;
 export declare function isInputMarker(v: unknown): v is InputMarker;
+declare const NOW_MARKER: unique symbol;
+export interface NowMarker {
+    readonly [NOW_MARKER]: true;
+}
+/** The current UTC instant in a policy `where`, resolved per request, as an ISO-8601
+ * string with a `Z` suffix — exactly what `new Date().toISOString()` produces.
+ *
+ * This is what makes a time boundary an ACL predicate rather than a filter every
+ * handler has to remember: `{ publishedAt: { lte: $now() } }` hides a row scheduled
+ * for the future from every caller the policy governs, not merely from the queries
+ * that thought to ask. `{ publishedAt: { isNull: false } }` cannot express it — a
+ * future timestamp is non-null, so a scheduled row would be readable the moment it
+ * is saved.
+ *
+ * Comparison is lexicographic TEXT, which is exact for ISO-8601 UTC but NOT
+ * cross-format: `expr.now()` defaults store `'YYYY-MM-DD HH:MM:SS'` (space, no `Z`)
+ * and will not compare correctly against this. Store the column with
+ * `toISOString()` — as the CMS `publish` field does — or compare it against
+ * `expr.now()`-shaped values only. */
+export declare function $now(): NowMarker;
+export declare function isNowMarker(v: unknown): v is NowMarker;
 export interface AllowMarker {
     readonly kind: "allow";
 }

package/dist/sdk/acl.js

@@ -1,5 +1,5 @@
 // ACL primitives — the portable definition layer: role(), policy(), allow(),
-// deny(), $identity(). Resolution semantics live in runtime/acl.ts.
+// deny(), $identity(), $now(). Resolution semantics live in runtime/acl.ts.
 //
 // Model: an Identity carries one or more roles. A policy grants a (role) access
 // to an (entity, action), optionally restricted by a row-level `where` predicate
@@ -27,6 +27,30 @@ export function $input(path) {
 export function isInputMarker(v) {
     return typeof v === "object" && v !== null && v[INPUT_MARKER] === true;
 }
+// --- $now markers: the request's evaluation instant inside a where rule, for a
+// time-boxed grant (scheduled publication, an expiring share link).
+const NOW_MARKER = Symbol.for("pramen.nowMarker");
+/** The current UTC instant in a policy `where`, resolved per request, as an ISO-8601
+ * string with a `Z` suffix — exactly what `new Date().toISOString()` produces.
+ *
+ * This is what makes a time boundary an ACL predicate rather than a filter every
+ * handler has to remember: `{ publishedAt: { lte: $now() } }` hides a row scheduled
+ * for the future from every caller the policy governs, not merely from the queries
+ * that thought to ask. `{ publishedAt: { isNull: false } }` cannot express it — a
+ * future timestamp is non-null, so a scheduled row would be readable the moment it
+ * is saved.
+ *
+ * Comparison is lexicographic TEXT, which is exact for ISO-8601 UTC but NOT
+ * cross-format: `expr.now()` defaults store `'YYYY-MM-DD HH:MM:SS'` (space, no `Z`)
+ * and will not compare correctly against this. Store the column with
+ * `toISOString()` — as the CMS `publish` field does — or compare it against
+ * `expr.now()`-shaped values only. */
+export function $now() {
+    return { [NOW_MARKER]: true };
+}
+export function isNowMarker(v) {
+    return typeof v === "object" && v !== null && v[NOW_MARKER] === true;
+}
 export function allow() {
     return { kind: "allow" };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "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

@@ -34,12 +34,13 @@ export { query, mutation, authorizeHandler } from "./sdk/handlers";
 export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
 
 // --- ACL ---
-export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
+export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker, isNowMarker } from "./sdk/acl";
 export type {
   Action,
   Identity,
   IdentityMarker,
   InputMarker,
+  NowMarker,
   Policy,
   PolicyRule,
   PolicyRules,

package/src/runtime/acl.ts

@@ -20,6 +20,7 @@ import {
   isDeny,
   isIdentityMarker,
   isInputMarker,
+  isNowMarker,
   isResolver,
 } from "../sdk/acl";
 import { and, compileWhere, evalExpr, FALSE, not, or, TRUE, type SqlExpr } from "./read-engine";
@@ -172,10 +173,12 @@ function getPath(obj: unknown, path: string): unknown {
 
 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.
+// Resolve a value that may be an $identity marker (against the caller), an
+// $input marker (against the request input — a capability/by-key grant), or a
+// $now marker (the evaluation instant). An unresolvable marker yields UNRESOLVED,
+// which makes its rule match nothing. $now always resolves.
 function resolveValue(v: unknown, identity: Identity | null, input: unknown): unknown {
+  if (isNowMarker(v)) return new Date().toISOString();
   if (isIdentityMarker(v)) {
     const value = getPath(identity, v.path);
     return value === undefined ? UNRESOLVED : value;
@@ -187,7 +190,7 @@ function resolveValue(v: unknown, identity: Identity | null, input: unknown): un
   return v;
 }
 
-// Resolve every $identity/$input marker in a SINGLE level of a where-rule (bare
+// Resolve every $identity/$input/$now marker in a SINGLE level of a where-rule (bare
 // values, operator objects, in/notIn arrays). AND/OR groups are split off by
 // `compileScopedWhere` before this runs, so this only ever sees plain columns.
 // Returns a plain WhereInput, or null if any marker is unresolvable — in which
@@ -199,7 +202,7 @@ function resolveValue(v: unknown, identity: Identity | null, input: unknown): un
 function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null, input: unknown): Record<string, unknown> | null {
   const out: Record<string, unknown> = {};
   for (const [key, v] of Object.entries(rule)) {
-    const isMarker = isIdentityMarker(v) || isInputMarker(v);
+    const isMarker = isIdentityMarker(v) || isInputMarker(v) || isNowMarker(v);
     if (v !== null && typeof v === "object" && !isMarker && !Array.isArray(v)) {
       const ops: Record<string, unknown> = {};
       for (const [op, val] of Object.entries(v as Record<string, unknown>)) {
@@ -317,7 +320,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
 
 /** Compile a where-rule (user query or policy) into a SqlExpr. Plain columns go
  * through the marker-resolving compiler; relation keys (`{ rel: { … } }`) become
- * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input
+ * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input/$now
  * markers; an unresolvable marker makes its branch match nothing. Schema-less
  * contexts (no relations) behave exactly like the flat compiler.
  *

package/src/sdk/acl.ts

@@ -1,5 +1,5 @@
 // ACL primitives — the portable definition layer: role(), policy(), allow(),
-// deny(), $identity(). Resolution semantics live in runtime/acl.ts.
+// deny(), $identity(), $now(). Resolution semantics live in runtime/acl.ts.
 //
 // Model: an Identity carries one or more roles. A policy grants a (role) access
 // to an (entity, action), optionally restricted by a row-level `where` predicate
@@ -60,6 +60,38 @@ export function isInputMarker(v: unknown): v is InputMarker {
   return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[INPUT_MARKER] === true;
 }
 
+// --- $now markers: the request's evaluation instant inside a where rule, for a
+// time-boxed grant (scheduled publication, an expiring share link).
+
+const NOW_MARKER = Symbol.for("pramen.nowMarker");
+
+export interface NowMarker {
+  readonly [NOW_MARKER]: true;
+}
+
+/** The current UTC instant in a policy `where`, resolved per request, as an ISO-8601
+ * string with a `Z` suffix — exactly what `new Date().toISOString()` produces.
+ *
+ * This is what makes a time boundary an ACL predicate rather than a filter every
+ * handler has to remember: `{ publishedAt: { lte: $now() } }` hides a row scheduled
+ * for the future from every caller the policy governs, not merely from the queries
+ * that thought to ask. `{ publishedAt: { isNull: false } }` cannot express it — a
+ * future timestamp is non-null, so a scheduled row would be readable the moment it
+ * is saved.
+ *
+ * Comparison is lexicographic TEXT, which is exact for ISO-8601 UTC but NOT
+ * cross-format: `expr.now()` defaults store `'YYYY-MM-DD HH:MM:SS'` (space, no `Z`)
+ * and will not compare correctly against this. Store the column with
+ * `toISOString()` — as the CMS `publish` field does — or compare it against
+ * `expr.now()`-shaped values only. */
+export function $now(): NowMarker {
+  return { [NOW_MARKER]: true };
+}
+
+export function isNowMarker(v: unknown): v is NowMarker {
+  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[NOW_MARKER] === true;
+}
+
 // --- allow / deny markers ---
 
 export interface AllowMarker {