@pramen/server 0.0.37 → 0.0.38

package/dist/auth.js

@@ -175,6 +175,10 @@ function toIdentity(claims) {
             ? [claims.role]
             : [];
     const identity = { roles, userId: (claims.sub ?? claims.userId) };
+    // Carry `exp` (a STANDARD claim, so the passthrough loop skips it) so a WebSocket can
+    // re-check expiry per message — its identity is fixed at upgrade and never re-verified.
+    if (typeof claims.exp === "number")
+        identity.exp = claims.exp;
     for (const [k, v] of Object.entries(claims)) {
         if (!STANDARD_CLAIMS.has(k))
             identity[k] = v; // carry custom claims (tier, …)

package/dist/durable-object.d.ts

@@ -79,6 +79,13 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     private get envBag();
     private filesFor;
     private identityOf;
+    /** Has this socket's token expired? `exp` (epoch seconds) rides the socket attachment
+     * from the upgrade-time identity. A synthetic / non-expiring identity has no `exp` and is
+     * never expired, so callPrivileged and admin sockets keep working. */
+    private isExpired;
+    /** Reject a message from an expired socket: send the protocol's auth-failure error frame,
+     * then close 4401 (the client should re-authenticate and reconnect). */
+    private rejectExpired;
     /** The durable per-socket auth/routing state (identity + tenant + partition), read
      * from the WS attachment. Survives hibernation; kept tiny to stay under workerd's cap. */
     private getAttachment;

package/dist/durable-object.js

@@ -24,13 +24,16 @@ import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
 import { compileAcl } from "./runtime/acl";
 import { DoSqliteDriver } from "./runtime/driver";
-import { BadRequest, toResponse, toWsError } from "./runtime/errors";
+import { BadRequest, Unauthorized, toResponse, toWsError } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
 import { registryKey } from "./runtime/registry";
 import { DEFAULT_PARTITION } from "./sdk/schema";
 import { createFiles, R2Adapter } from "./runtime/storage";
 /** Per-socket subscription cap — bounds memory and per-mutation re-run cost. */
 const MAX_SUBSCRIPTIONS = 64;
+/** WebSocket close code for an auth failure (RFC 6455 leaves 4000-4999 to the app;
+ * 4401 mirrors HTTP 401). Sent when a socket's token has expired since upgrade. */
+const WS_CLOSE_UNAUTHORIZED = 4401;
 export class PramenDOBase extends DurableObject {
     app;
     acl;
@@ -276,9 +279,15 @@ export class PramenDOBase extends DurableObject {
         // socket's (tenant, partition) — fixed at connect time, survives via the attachment
         // — and ensure the schema is migrated before any handler/ctx.db work. Idempotent
         // (the `migrated` flag), so a no-op after the first call.
-        const { tenant, partition } = this.getAttachment(ws);
-        this.tenant = tenant;
-        this.partition = partition;
+        const att = this.getAttachment(ws);
+        this.tenant = att.tenant;
+        this.partition = att.partition;
+        // The token was verified ONCE at upgrade; a live/hibernating socket can outlive its
+        // TTL. Re-check `exp` per message so an expired session can't keep calling/subscribing
+        // (role changes + the denylist only bite on reconnect, which this forces). Fail the
+        // frame and close 4401 so the client re-auths. Synthetic identities carry no exp.
+        if (this.isExpired(att.identity))
+            return this.rejectExpired(ws, msg.id);
         await this.ensureMigrated();
         switch (msg.type) {
             case "subscribe":
@@ -355,6 +364,19 @@ export class PramenDOBase extends DurableObject {
         for (const ws of this.ctx.getWebSockets()) {
             try {
                 const att = this.getAttachment(ws);
+                // A live socket whose token expired while connected must not keep receiving pushes.
+                // Close it 4401 and drop its subscriptions instead of pushing (an expired hibernating
+                // socket already has no in-memory subs, so this only bites still-live ones).
+                if (this.isExpired(att.identity)) {
+                    try {
+                        ws.close(WS_CLOSE_UNAUTHORIZED, "session expired");
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                    this.subsBySocket.delete(ws);
+                    continue;
+                }
                 const subs = this.getSubs(ws);
                 let dirty = false;
                 for (const sub of subs) {
@@ -537,6 +559,24 @@ export class PramenDOBase extends DurableObject {
             return null;
         }
     }
+    /** Has this socket's token expired? `exp` (epoch seconds) rides the socket attachment
+     * from the upgrade-time identity. A synthetic / non-expiring identity has no `exp` and is
+     * never expired, so callPrivileged and admin sockets keep working. */
+    isExpired(identity) {
+        const exp = identity?.exp;
+        return typeof exp === "number" && Date.now() / 1000 >= exp;
+    }
+    /** Reject a message from an expired socket: send the protocol's auth-failure error frame,
+     * then close 4401 (the client should re-authenticate and reconnect). */
+    rejectExpired(ws, id) {
+        this.send(ws, toWsError(id, new Unauthorized("session expired")));
+        try {
+            ws.close(WS_CLOSE_UNAUTHORIZED, "session expired");
+        }
+        catch {
+            /* already closing */
+        }
+    }
     /** The durable per-socket auth/routing state (identity + tenant + partition), read
      * from the WS attachment. Survives hibernation; kept tiny to stay under workerd's cap. */
     getAttachment(ws) {

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, Han
 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 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";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";

package/dist/index.js

@@ -14,6 +14,8 @@ 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";
+// --- kv (ctx.kv) + session denylist (hard token revocation) ---
+export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 // --- mail (ctx.mail) ---
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";

package/dist/runtime/kv.d.ts

@@ -21,3 +21,14 @@ export declare class Kv {
         cursor: string | null;
     }>;
 }
+/** Revoke every outstanding token for `username` for up to `ttlSeconds` (the session
+ * TTL). Called when an account is deactivated / deleted. The entry self-expires, so the
+ * denylist never accumulates beyond the current revocation window. */
+export declare function denySession(kv: Kv, username: string, ttlSeconds: number): Promise<void>;
+/** Lift a prior `denySession` (e.g. on reactivation). The key is username-scoped, so
+ * without this a reactivated account would stay locked out — even for a fresh login —
+ * until the denylist entry expired on its own. */
+export declare function allowSession(kv: Kv, username: string): Promise<void>;
+/** Is there a live denylist entry for `username`? The Worker consults this per
+ * authenticated request (only when a `sub` is present) to fail a revoked token closed. */
+export declare function isSessionDenied(kv: Kv, username: string): Promise<boolean>;

package/dist/runtime/kv.js

@@ -39,3 +39,40 @@ export class Kv {
         };
     }
 }
+// --- session denylist (hard token revocation) -------------------------------
+//
+// The core is stateless verify-only: roles/active are baked into a token at login and
+// there is no per-request DB lookup. To revoke a token BEFORE its `exp` (deactivate /
+// delete / compromise), we keep a tiny KV denylist keyed by username (= the JWT `sub`).
+// The Worker checks it right after resolving identity — a denied `sub` fails closed
+// (401), never silently downgrades to anonymous.
+//
+// The entry carries an `expirationTtl` equal to the session TTL, so it self-expires
+// exactly when the last token that could have been outstanding at revocation time does:
+// the list can only ever hold recently-revoked users and never grows unbounded. The key
+// is username-scoped (not per-token), so it blocks EVERY token for that user — including
+// a fresh login — which is why reactivation must lift it (see `allowSession`).
+/** App-relative key (the `Kv` facade adds its own `app:` prefix). Writer (auth) and
+ * reader (Worker) both route through these helpers so the namespacing always agrees. */
+const denyKey = (username) => `authDenied:${username}`;
+/** Cloudflare KV rejects an `expirationTtl` below 60s — clamp so a short session TTL
+ * still produces a valid (if slightly over-long) denylist entry. */
+const MIN_KV_TTL_SECONDS = 60;
+/** Revoke every outstanding token for `username` for up to `ttlSeconds` (the session
+ * TTL). Called when an account is deactivated / deleted. The entry self-expires, so the
+ * denylist never accumulates beyond the current revocation window. */
+export async function denySession(kv, username, ttlSeconds) {
+    const ttl = Math.max(MIN_KV_TTL_SECONDS, Math.trunc(ttlSeconds) || MIN_KV_TTL_SECONDS);
+    await kv.put(denyKey(username), "1", { expirationTtl: ttl });
+}
+/** Lift a prior `denySession` (e.g. on reactivation). The key is username-scoped, so
+ * without this a reactivated account would stay locked out — even for a fresh login —
+ * until the denylist entry expired on its own. */
+export async function allowSession(kv, username) {
+    await kv.delete(denyKey(username));
+}
+/** Is there a live denylist entry for `username`? The Worker consults this per
+ * authenticated request (only when a `sub` is present) to fail a revoked token closed. */
+export async function isSessionDenied(kv, username) {
+    return (await kv.get(denyKey(username))) != null;
+}

package/dist/sdk/acl.d.ts

@@ -3,6 +3,11 @@ export type Action = "read" | "create" | "update" | "delete";
 export interface Identity {
     role?: string;
     roles?: string[];
+    /** The verified token's `exp` (epoch seconds), when present. Carried so a long-lived
+     * WebSocket — whose identity is fixed at upgrade and never re-verified — can enforce
+     * expiry per message (see durable-object.ts). Absent for non-expiring / synthetic
+     * (callPrivileged) identities, which are therefore never treated as expired. */
+    exp?: number;
     [key: string]: unknown;
 }
 declare const IDENTITY_MARKER: unique symbol;

package/dist/worker.js

@@ -14,7 +14,7 @@ import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
 import { D1Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
-import { Kv } from "./runtime/kv";
+import { Kv, isSessionDenied } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
 import { createFiles, handleFileRequest, handleMediaRequest, R2Adapter } from "./runtime/storage";
 import { DEFAULT_PARTITION, partitionsOf } from "./sdk/schema";
@@ -245,6 +245,17 @@ export function makeWorker(app) {
                 req = new Request(request, { headers: h });
             }
             const identity = await resolveIdentity(req, strategyFor(env));
+            // Hard revocation (deactivate / delete / compromise), independent of token TTL: a
+            // revoked `sub` is on the KV denylist (written by @pramen/auth's setUserActive(false)
+            // / deleteUser, self-expiring at the session TTL). Check it HERE, at identity-resolution
+            // time — before the DO proxy AND the D1 store path, and before the admin routes — so it
+            // covers HTTP and the WebSocket upgrade alike. A denied token fails CLOSED (401); we do
+            // NOT silently downgrade to anonymous — a revoked user should see a clear auth failure.
+            // Synthetic identities (callPrivileged) never pass through here, so they're unaffected.
+            const sub = typeof identity?.userId === "string" ? identity.userId : undefined;
+            if (sub && (await isSessionDenied(new Kv(env.KV), sub))) {
+                return withCors(json({ ok: false, error: "session revoked", code: "unauthorized" }, 401), cors);
+            }
             // --- admin: list known (tenant, partition) DOs from the registry ---
             if (url.pathname === "/tenants") {
                 if (!isAdmin(identity))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "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/auth.ts

@@ -226,6 +226,9 @@ function toIdentity(claims: Record<string, unknown>): Identity {
       ? [claims.role]
       : [];
   const identity: Identity = { roles, userId: (claims.sub ?? claims.userId) as string | undefined };
+  // Carry `exp` (a STANDARD claim, so the passthrough loop skips it) so a WebSocket can
+  // re-check expiry per message — its identity is fixed at upgrade and never re-verified.
+  if (typeof claims.exp === "number") identity.exp = claims.exp;
   for (const [k, v] of Object.entries(claims)) {
     if (!STANDARD_CLAIMS.has(k)) identity[k] = v; // carry custom claims (tier, …)
   }

package/src/durable-object.ts

@@ -25,7 +25,7 @@ import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
 import { compileAcl, type AclContext, type CompiledAcl } from "./runtime/acl";
 import { DoSqliteDriver, type Driver } from "./runtime/driver";
-import { BadRequest, toResponse, toWsError } from "./runtime/errors";
+import { BadRequest, Unauthorized, toResponse, toWsError } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
 import { registryKey } from "./runtime/registry";
 import { DEFAULT_PARTITION } from "./sdk/schema";
@@ -65,6 +65,10 @@ export interface DoEnv {
 /** Per-socket subscription cap — bounds memory and per-mutation re-run cost. */
 const MAX_SUBSCRIPTIONS = 64;
 
+/** WebSocket close code for an auth failure (RFC 6455 leaves 4000-4999 to the app;
+ * 4401 mirrors HTTP 401). Sent when a socket's token has expired since upgrade. */
+const WS_CLOSE_UNAUTHORIZED = 4401;
+
 export class PramenDOBase extends DurableObject<DoEnv> {
   private readonly app: PramenApp;
   private readonly acl: CompiledAcl;
@@ -336,9 +340,16 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     // socket's (tenant, partition) — fixed at connect time, survives via the attachment
     // — and ensure the schema is migrated before any handler/ctx.db work. Idempotent
     // (the `migrated` flag), so a no-op after the first call.
-    const { tenant, partition } = this.getAttachment(ws);
-    this.tenant = tenant;
-    this.partition = partition;
+    const att = this.getAttachment(ws);
+    this.tenant = att.tenant;
+    this.partition = att.partition;
+
+    // The token was verified ONCE at upgrade; a live/hibernating socket can outlive its
+    // TTL. Re-check `exp` per message so an expired session can't keep calling/subscribing
+    // (role changes + the denylist only bite on reconnect, which this forces). Fail the
+    // frame and close 4401 so the client re-auths. Synthetic identities carry no exp.
+    if (this.isExpired(att.identity)) return this.rejectExpired(ws, msg.id);
+
     await this.ensureMigrated();
 
     switch (msg.type) {
@@ -417,6 +428,18 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     for (const ws of this.ctx.getWebSockets()) {
       try {
         const att = this.getAttachment(ws);
+        // A live socket whose token expired while connected must not keep receiving pushes.
+        // Close it 4401 and drop its subscriptions instead of pushing (an expired hibernating
+        // socket already has no in-memory subs, so this only bites still-live ones).
+        if (this.isExpired(att.identity)) {
+          try {
+            ws.close(WS_CLOSE_UNAUTHORIZED, "session expired");
+          } catch {
+            /* already closing */
+          }
+          this.subsBySocket.delete(ws);
+          continue;
+        }
         const subs = this.getSubs(ws);
         let dirty = false;
         for (const sub of subs) {
@@ -604,6 +627,25 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
   }
 
+  /** Has this socket's token expired? `exp` (epoch seconds) rides the socket attachment
+   * from the upgrade-time identity. A synthetic / non-expiring identity has no `exp` and is
+   * never expired, so callPrivileged and admin sockets keep working. */
+  private isExpired(identity: Identity | null): boolean {
+    const exp = identity?.exp;
+    return typeof exp === "number" && Date.now() / 1000 >= exp;
+  }
+
+  /** Reject a message from an expired socket: send the protocol's auth-failure error frame,
+   * then close 4401 (the client should re-authenticate and reconnect). */
+  private rejectExpired(ws: WebSocket, id: string): void {
+    this.send(ws, toWsError(id, new Unauthorized("session expired")));
+    try {
+      ws.close(WS_CLOSE_UNAUTHORIZED, "session expired");
+    } catch {
+      /* already closing */
+    }
+  }
+
   /** The durable per-socket auth/routing state (identity + tenant + partition), read
    * from the WS attachment. Survives hibernation; kept tiny to stay under workerd's cap. */
   private getAttachment(ws: WebSocket): SocketAttachment {

package/src/index.ts

@@ -71,6 +71,9 @@ export type {
   WhereOps,
 } from "./sdk/infer";
 
+// --- kv (ctx.kv) + session denylist (hard token revocation) ---
+export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
+
 // --- files ---
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";

package/src/runtime/kv.ts

@@ -45,3 +45,46 @@ export class Kv {
     };
   }
 }
+
+// --- session denylist (hard token revocation) -------------------------------
+//
+// The core is stateless verify-only: roles/active are baked into a token at login and
+// there is no per-request DB lookup. To revoke a token BEFORE its `exp` (deactivate /
+// delete / compromise), we keep a tiny KV denylist keyed by username (= the JWT `sub`).
+// The Worker checks it right after resolving identity — a denied `sub` fails closed
+// (401), never silently downgrades to anonymous.
+//
+// The entry carries an `expirationTtl` equal to the session TTL, so it self-expires
+// exactly when the last token that could have been outstanding at revocation time does:
+// the list can only ever hold recently-revoked users and never grows unbounded. The key
+// is username-scoped (not per-token), so it blocks EVERY token for that user — including
+// a fresh login — which is why reactivation must lift it (see `allowSession`).
+
+/** App-relative key (the `Kv` facade adds its own `app:` prefix). Writer (auth) and
+ * reader (Worker) both route through these helpers so the namespacing always agrees. */
+const denyKey = (username: string): string => `authDenied:${username}`;
+
+/** Cloudflare KV rejects an `expirationTtl` below 60s — clamp so a short session TTL
+ * still produces a valid (if slightly over-long) denylist entry. */
+const MIN_KV_TTL_SECONDS = 60;
+
+/** Revoke every outstanding token for `username` for up to `ttlSeconds` (the session
+ * TTL). Called when an account is deactivated / deleted. The entry self-expires, so the
+ * denylist never accumulates beyond the current revocation window. */
+export async function denySession(kv: Kv, username: string, ttlSeconds: number): Promise<void> {
+  const ttl = Math.max(MIN_KV_TTL_SECONDS, Math.trunc(ttlSeconds) || MIN_KV_TTL_SECONDS);
+  await kv.put(denyKey(username), "1", { expirationTtl: ttl });
+}
+
+/** Lift a prior `denySession` (e.g. on reactivation). The key is username-scoped, so
+ * without this a reactivated account would stay locked out — even for a fresh login —
+ * until the denylist entry expired on its own. */
+export async function allowSession(kv: Kv, username: string): Promise<void> {
+  await kv.delete(denyKey(username));
+}
+
+/** Is there a live denylist entry for `username`? The Worker consults this per
+ * authenticated request (only when a `sub` is present) to fail a revoked token closed. */
+export async function isSessionDenied(kv: Kv, username: string): Promise<boolean> {
+  return (await kv.get(denyKey(username))) != null;
+}

package/src/sdk/acl.ts

@@ -12,6 +12,11 @@ export type Action = "read" | "create" | "update" | "delete";
 export interface Identity {
   role?: string;
   roles?: string[];
+  /** The verified token's `exp` (epoch seconds), when present. Carried so a long-lived
+   * WebSocket — whose identity is fixed at upgrade and never re-verified — can enforce
+   * expiry per message (see durable-object.ts). Absent for non-expiring / synthetic
+   * (callPrivileged) identities, which are therefore never treated as expired. */
+  exp?: number;
   [key: string]: unknown;
 }
 

package/src/worker.ts

@@ -15,7 +15,7 @@ import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
 import { D1Driver, type D1SessionStart, type Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
-import { Kv } from "./runtime/kv";
+import { Kv, isSessionDenied } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
 import { createFiles, handleFileRequest, handleMediaRequest, R2Adapter } from "./runtime/storage";
 import type { Identity } from "./sdk/acl";
@@ -312,6 +312,18 @@ export function makeWorker(app: PramenApp) {
 
     const identity = await resolveIdentity(req, strategyFor(env));
 
+    // Hard revocation (deactivate / delete / compromise), independent of token TTL: a
+    // revoked `sub` is on the KV denylist (written by @pramen/auth's setUserActive(false)
+    // / deleteUser, self-expiring at the session TTL). Check it HERE, at identity-resolution
+    // time — before the DO proxy AND the D1 store path, and before the admin routes — so it
+    // covers HTTP and the WebSocket upgrade alike. A denied token fails CLOSED (401); we do
+    // NOT silently downgrade to anonymous — a revoked user should see a clear auth failure.
+    // Synthetic identities (callPrivileged) never pass through here, so they're unaffected.
+    const sub = typeof identity?.userId === "string" ? identity.userId : undefined;
+    if (sub && (await isSessionDenied(new Kv(env.KV), sub))) {
+      return withCors(json({ ok: false, error: "session revoked", code: "unauthorized" }, 401), cors);
+    }
+
     // --- admin: list known (tenant, partition) DOs from the registry ---
     if (url.pathname === "/tenants") {
       if (!isAdmin(identity)) return withCors(forbidden("tenants"), cors);