@astram/guard 0.1.0

package/dist/session/redis-hot-session-store.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * `RedisHotSessionStore` — the concrete hot {@link HotSessionStore} for
+ * `@astram/guard`, backed by `ioredis` against the Layer-2 Redis (ADR-0013 hot
+ * tier). Serves the per-request read path and is (re)populated at lifecycle events.
+ *
+ * ADR-0003 (why HERE, not Core): `ioredis` is a real runtime dependency; Core
+ * defines only the PORT. Injected into `createSessionAuthority({ hotStore })` and
+ * used by the free `readHotSession(hotStore, id)` per-request path.
+ *
+ * ⛔ THE CRITICAL CONTRACT (ADR-0013/0016): `getHotSession` MUST distinguish
+ *   - `{ kind: 'found', state }` — a live hot record,
+ *   - `{ kind: 'absent' }`       — Redis is UP and simply has no such key (a miss),
+ *   - `{ kind: 'unavailable' }`  — Redis CANNOT answer (down/timeout/refused).
+ * The engine fails CLOSED on `unavailable` and NEVER falls back to the durable
+ * tier. Conflating unavailable→absent would fail open on a blip; conflating
+ * absent→unavailable would log users out on a normal miss. So we catch connection
+ * errors and map ONLY those to `unavailable`; a clean `null` GET reply is `absent`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisHotSessionStore = exports.SHIELD_HOT_SESSION_STORE = void 0;
+/** The DI token the store is bound under. */
+exports.SHIELD_HOT_SESSION_STORE = Symbol('SHIELD_HOT_SESSION_STORE');
+/**
+ * A connection-level failure — Redis genuinely cannot answer. ioredis surfaces
+ * these as errors whose `code` is a socket/connection code, or (when the client
+ * is offline and not queuing) a MaxRetriesPerRequest/"Connection is closed"
+ * message. We treat any GET-time error as "cannot answer" → `unavailable`
+ * (fail-closed) rather than risk mis-reading it as a normal miss.
+ */
+function isConnectionFailure(err) {
+    if (err === null || typeof err !== 'object')
+        return false;
+    const e = err;
+    const code = typeof e.code === 'string' ? e.code : '';
+    const message = typeof e.message === 'string' ? e.message : '';
+    const CONN_CODES = new Set([
+        'ECONNREFUSED',
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'EPIPE',
+        'ENOTFOUND',
+        'EAI_AGAIN',
+        'NR_CLOSED',
+    ]);
+    if (CONN_CODES.has(code))
+        return true;
+    return (/connection is closed/i.test(message) ||
+        /max retries per request/i.test(message) ||
+        /connection to redis/i.test(message) ||
+        /stream isn't writeable/i.test(message));
+}
+class RedisHotSessionStore {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    async putHotSession(key, state, ttlMs) {
+        // JSON blob under the key with a PX (ms) TTL = the access-token TTL. cachedFacts
+        // is an opaque slot — we serialize whatever the engine passes (null at seed).
+        const payload = JSON.stringify(state);
+        await this.redis.set(key, payload, 'PX', Math.max(1, Math.floor(ttlMs)));
+    }
+    async getHotSession(key) {
+        let raw;
+        try {
+            raw = await this.redis.get(key);
+        }
+        catch (err) {
+            // ⛔ Cannot answer → fail-closed signal. NEVER a silent miss.
+            if (isConnectionFailure(err))
+                return { kind: 'unavailable' };
+            // Any other error is also treated as cannot-answer (conservative: never
+            // downgrade an unknown fault to a normal `absent` that could fail open).
+            return { kind: 'unavailable' };
+        }
+        if (raw === null)
+            return { kind: 'absent' }; // Redis is UP; genuine miss.
+        try {
+            const state = JSON.parse(raw);
+            if (state === null || typeof state !== 'object' || typeof state.sessionId !== 'string') {
+                // Corrupt payload — treat as a miss (the value will be re-populated at the
+                // next refresh); do NOT surface `found` with a malformed state.
+                return { kind: 'absent' };
+            }
+            return { kind: 'found', state };
+        }
+        catch {
+            return { kind: 'absent' };
+        }
+    }
+    async deleteHotSession(key) {
+        try {
+            await this.redis.del(key);
+        }
+        catch {
+            // Best-effort delete; a delete against a down Redis is retried at the next
+            // lifecycle event, and the durable revoke already refuses future refreshes.
+        }
+    }
+}
+exports.RedisHotSessionStore = RedisHotSessionStore;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@astram/guard",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@astram/core": "workspace:*",
+    "argon2": "^0.41.1",
+    "ioredis": "^5.4.1",
+    "mariadb": "^3.4.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11",
+    "@nestjs/core": "^11",
+    "reflect-metadata": "^0.2",
+    "rxjs": "^7"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "@types/supertest": "^6.0.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "supertest": "^7.0.0",
+    "typescript": "^5.7.0",
+    "unplugin-swc": "^1.5.1",
+    "vitest": "^2.1.8"
+  }
+}