@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/app/services/cache/Cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Framework-wide `Cache` interface.
+ *
+ * Two reference implementations ship in v4.0:
+ *   - `RedisCache` — production default, msgpackr-serialized, with
+ *     tag-based invalidation via Redis Sets.
+ *   - `InMemoryCache` — `lru-cache`-backed; intended for tests + dev
+ *     fallback when Redis is unavailable.
+ *
+ * Consumers usually don't construct caches directly — `cached(key, ttl, fn)`
+ * is the high-level helper that hides the lookup / miss / store dance.
+ *
+ * The interface is intentionally narrow: any backend that can do `get`,
+ * `set` (with TTL), `del`, and tag-tracking can plug in. Future v4.x
+ * adapters (Memcached, Cloudflare KV, Upstash) implement the same contract.
+ */
+export interface CacheSetOptions {
+    /** TTL in seconds. `undefined` means no expiry (use sparingly). */
+    ttlSec?: number;
+    /**
+     * Tag this key under each label. `invalidateTag(tag)` later wipes all keys
+     * sharing the tag — useful for "everything related to user X" or
+     * "everything in module Y".
+     */
+    tags?: readonly string[];
+}
+export interface Cache {
+    /** Returns `null` on miss. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Store with optional TTL + tags. Idempotent. */
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    /**
+     * Atomic SET-IF-ABSENT. Stores `value` if no entry already exists at `key`,
+     * returning `true`; returns `false` when an entry is present (no-op).
+     *
+     * Used as a low-level claim / lock primitive — the idempotency middleware
+     * uses it to deduplicate concurrent requests sharing an `Idempotency-Key`.
+     * Tags are NOT supported here (locks should not survive `invalidateTag`).
+     *
+     * Redis: implemented via `SET NX EX` (atomic at the Redis server).
+     * In-memory: the `has` / `set` body runs synchronously inside the async
+     * function — within a single event-loop tick the check + write is a true
+     * CAS.
+     *
+     * **F19 — Atomicity invariant.** Implementations MUST run the check + write
+     * in one continuation (no `await` between them). A future refactor that
+     * inserts an `await` silently breaks idempotency under concurrent load on
+     * a public app — multiple callers would see an empty slot, all "claim" the
+     * key, and the cache ends up holding the last writer's value with every
+     * caller observing `true`. The regression test in
+     * `InMemoryCache.test.ts` (100 concurrent `setIfAbsent("same-key")` →
+     * exactly one `true`) is the canary that catches the regression.
+     */
+    setIfAbsent<T = unknown>(key: string, value: T, opts?: {
+        ttlSec?: number;
+    }): Promise<boolean>;
+    /** Delete one or many keys. Missing keys are silently ignored. */
+    del(key: string | readonly string[]): Promise<void>;
+    /**
+     * Wipe every key recorded under `tag`, plus the tag-tracking record itself.
+     * Use for "user updated → invalidate everything tagged `user:<id>`".
+     */
+    invalidateTag(tag: string): Promise<void>;
+    /**
+     * Optional admin / test hook. Implementations that can't cheaply enumerate
+     * may throw. Avoid in production paths.
+     */
+    clear?(): Promise<void>;
+}
+//# sourceMappingURL=Cache.d.ts.map

package/lib/app/services/cache/Cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cache/Cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,KAAK;IACpB,8BAA8B;IAC9B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEjD,kDAAkD;IAClD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9F,kEAAkE;IAClE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/lib/app/services/cache/Cache.js

@@ -0,0 +1,18 @@
+/**
+ * Framework-wide `Cache` interface.
+ *
+ * Two reference implementations ship in v4.0:
+ *   - `RedisCache` — production default, msgpackr-serialized, with
+ *     tag-based invalidation via Redis Sets.
+ *   - `InMemoryCache` — `lru-cache`-backed; intended for tests + dev
+ *     fallback when Redis is unavailable.
+ *
+ * Consumers usually don't construct caches directly — `cached(key, ttl, fn)`
+ * is the high-level helper that hides the lookup / miss / store dance.
+ *
+ * The interface is intentionally narrow: any backend that can do `get`,
+ * `set` (with TTL), `del`, and tag-tracking can plug in. Future v4.x
+ * adapters (Memcached, Cloudflare KV, Upstash) implement the same contract.
+ */
+export {};
+//# sourceMappingURL=Cache.js.map

package/lib/app/services/cache/Cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../../../src/app/services/cache/Cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/lib/app/services/cache/InMemoryCache.d.ts

@@ -0,0 +1,35 @@
+import type { Cache, CacheSetOptions } from "./Cache.js";
+/**
+ * `lru-cache`-backed cache used in tests and as a graceful fallback when
+ * Redis is unavailable.
+ *
+ * Tag tracking is in-process only — the `tagIndex` Map mirrors the Redis
+ * Sets that `RedisCache` uses. `invalidateTag(tag)` walks the index +
+ * deletes the keys + drops the tag set, mirroring Redis behavior.
+ *
+ * Designed for *single-process* use only. In a multi-instance deployment
+ * each instance has its own cache, so tag invalidation in one instance
+ * does NOT propagate. This is acceptable for the test-fixture and
+ * dev-fallback use cases. Production must use `RedisCache`.
+ */
+export interface InMemoryCacheOptions {
+    /** Max number of entries before LRU eviction. Default 10_000. */
+    max?: number;
+    /** Default TTL (ms) for entries created without a TTL. */
+    defaultTtlMs?: number;
+}
+export declare class InMemoryCache implements Cache {
+    private store;
+    /** tag → set of cache keys tagged with it. */
+    private tagIndex;
+    constructor(opts?: InMemoryCacheOptions);
+    get<T = unknown>(key: string): Promise<T | null>;
+    setIfAbsent<T = unknown>(key: string, value: T, opts?: {
+        ttlSec?: number;
+    }): Promise<boolean>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    del(key: string | readonly string[]): Promise<void>;
+    invalidateTag(tag: string): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=InMemoryCache.d.ts.map

package/lib/app/services/cache/InMemoryCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryCache.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cache/InMemoryCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AASD,qBAAa,aAAc,YAAW,KAAK;IACzC,OAAO,CAAC,KAAK,CAAwB;IACrC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,IAAI,GAAE,oBAAyB;IAQrC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAMhD,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7B,OAAO,CAAC,OAAO,CAAC;IAYb,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/lib/app/services/cache/InMemoryCache.js

@@ -0,0 +1,76 @@
+import { LRUCache } from "lru-cache";
+export class InMemoryCache {
+    store;
+    /** tag → set of cache keys tagged with it. */
+    tagIndex = new Map();
+    constructor(opts = {}) {
+        this.store = new LRUCache({
+            max: opts.max ?? 10_000,
+            ttl: opts.defaultTtlMs,
+            ttlAutopurge: opts.defaultTtlMs !== undefined,
+        });
+    }
+    async get(key) {
+        const box = this.store.get(key);
+        if (box === undefined)
+            return null;
+        return box.v;
+    }
+    async setIfAbsent(key, value, opts = {}) {
+        if (this.store.has(key))
+            return false;
+        const ttlMs = opts.ttlSec !== undefined ? opts.ttlSec * 1000 : undefined;
+        const box = { v: value };
+        if (ttlMs !== undefined && ttlMs > 0) {
+            this.store.set(key, box, { ttl: ttlMs });
+        }
+        else {
+            this.store.set(key, box);
+        }
+        return true;
+    }
+    async set(key, value, opts = {}) {
+        const ttlMs = opts.ttlSec !== undefined ? opts.ttlSec * 1000 : undefined;
+        const box = { v: value };
+        if (ttlMs !== undefined && ttlMs > 0) {
+            this.store.set(key, box, { ttl: ttlMs });
+        }
+        else {
+            this.store.set(key, box);
+        }
+        if (opts.tags) {
+            for (const tag of opts.tags) {
+                let bucket = this.tagIndex.get(tag);
+                if (!bucket) {
+                    bucket = new Set();
+                    this.tagIndex.set(tag, bucket);
+                }
+                bucket.add(key);
+            }
+        }
+    }
+    async del(key) {
+        const keys = Array.isArray(key) ? key : [key];
+        for (const k of keys) {
+            this.store.delete(k);
+            // Also drop from any tag buckets so invalidateTag doesn't try to
+            // delete already-evicted keys.
+            for (const bucket of this.tagIndex.values()) {
+                bucket.delete(k);
+            }
+        }
+    }
+    async invalidateTag(tag) {
+        const bucket = this.tagIndex.get(tag);
+        if (!bucket)
+            return;
+        for (const k of bucket)
+            this.store.delete(k);
+        this.tagIndex.delete(tag);
+    }
+    async clear() {
+        this.store.clear();
+        this.tagIndex.clear();
+    }
+}
+//# sourceMappingURL=InMemoryCache.js.map

package/lib/app/services/cache/InMemoryCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryCache.js","sourceRoot":"","sources":["../../../../src/app/services/cache/InMemoryCache.ts"],"names":[],"mappings":"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"}

package/lib/app/services/cache/RedisCache.d.ts

@@ -0,0 +1,99 @@
+import type { Cache, CacheSetOptions } from "./Cache.js";
+/**
+ * Redis-backed cache with msgpackr serialization.
+ *
+ * Production default. Designed to be Redis-client-agnostic: any object that
+ * implements the methods in `RedisLike` works (production: ioredis client;
+ * tests: hand-rolled fake).
+ *
+ * Serialization: msgpackr encodes/decodes via Buffer — faster than JSON,
+ * preserves Date / Map / Set / undefined / bigint that JSON loses.
+ *
+ * Tag tracking: each `set(key, value, { tags })` SADDs the key into a
+ * sibling Redis Set named `<tagPrefix><tag>`. `invalidateTag(tag)` SMEMBERs,
+ * deletes them all, and drops the tag set. Atomic for typical use because
+ * tag-set membership and value-key live in the same Redis instance — for
+ * cluster mode, hash-tag the keys to keep them on one shard.
+ *
+ * Key namespacing: every key is prefixed with `keyPrefix` so cache content
+ * can't bleed across services or framework versions.
+ */
+export interface RedisLike {
+    set(key: string, value: Buffer | string, ...args: unknown[]): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+    getBuffer(key: string): Promise<Buffer | null>;
+    del(...keys: string[]): Promise<number>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    expire(key: string, seconds: number): Promise<number>;
+}
+export interface RedisCacheOptions {
+    /** Redis client. */
+    client: RedisLike;
+    /**
+     * String prepended to every key (and tag set name) to namespace the
+     * cache. Recommended `${SERVICE_NAME}:${pkg.version}:` so a deploy of
+     * a new version can't read stale entries.
+     */
+    keyPrefix?: string;
+    /** Tag-set namespace prefix. Default `"tag:"`. */
+    tagPrefix?: string;
+    /**
+     * **Opt-in (F14) HMAC integrity key.** When set, every `set` /
+     * `setIfAbsent` writes `[0x01][HMAC-SHA256(key||msgpackrBytes)][msgpackrBytes]`
+     * into Redis; every `get` checks the MAC and returns `null`
+     * (deleting the poisoned entry in the background) on mismatch.
+     * Disabled by default — adopters running a dedicated Redis don't
+     * need it. Enable when the Redis tier is shared with untrusted
+     * clustermates (multi-tenant Redis, leaked password, co-located
+     * service with the Redis password).
+     *
+     * `defineEnv` is the recommended boundary: source from an env
+     * `CACHE_SIGNING_KEY` of ≥32 random bytes, rotate independently
+     * of JWT keys. The framework reads this once at construction;
+     * rotating means restarting the process with a new value.
+     *
+     * Documented in `.cursor/rules/security.mdc` (Cache section).
+     */
+    signingKey?: string;
+}
+export declare class RedisCache implements Cache {
+    private client;
+    private keyPrefix;
+    private tagPrefix;
+    private packr;
+    private signingKey?;
+    constructor(opts: RedisCacheOptions);
+    private k;
+    private t;
+    /**
+     * Wrap raw msgpackr bytes with the F14 signed frame when signing is
+     * enabled. The MAC binds the value to the namespaced key — an
+     * attacker who steals one key's signed payload cannot replay it
+     * under a different key.
+     */
+    private frame;
+    /**
+     * Unwrap a signed frame, verifying the MAC. Returns `null` (and
+     * fires a fire-and-forget delete of the offending key) on any
+     * mismatch — frame byte unrecognized, MAC truncated, MAC fails to
+     * verify, or signing was enabled but the value is unsigned (a
+     * pre-signing entry or a tampering attempt). When signing is
+     * disabled, returns the buffer as-is.
+     */
+    private unframe;
+    /**
+     * Best-effort delete of a poisoned entry. Run in the background so
+     * a failure (or a Redis hiccup) doesn't shadow the caller's
+     * read-returns-null semantics.
+     */
+    private dropPoisoned;
+    get<T = unknown>(key: string): Promise<T | null>;
+    setIfAbsent<T = unknown>(key: string, value: T, opts?: {
+        ttlSec?: number;
+    }): Promise<boolean>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    del(key: string | readonly string[]): Promise<void>;
+    invalidateTag(tag: string): Promise<void>;
+}
+//# sourceMappingURL=RedisCache.d.ts.map

package/lib/app/services/cache/RedisCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisCache.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cache/RedisCache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBzD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,MAAM,EAAE,SAAS,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,UAAW,YAAW,KAAK;IACtC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,UAAU,CAAC,CAAS;gBAEhB,IAAI,EAAE,iBAAiB;IAYnC,OAAO,CAAC,CAAC;IAIT,OAAO,CAAC,CAAC;IAIT;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IASb;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAuBf;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAId,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAShD,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7B,OAAO,CAAC,OAAO,CAAC;IAYb,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhD"}

package/lib/app/services/cache/RedisCache.js

@@ -0,0 +1,150 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Packr } from "msgpackr";
+/**
+ * Frame version byte for HMAC-signed RedisCache values (F14). The
+ * first byte of a signed payload is one of these magic markers so
+ * `get()` can:
+ *   - tell signed values from legacy unsigned ones (signing was
+ *     introduced post-shipping; consumers may have old entries),
+ *   - rotate the MAC scheme in a future release without breaking
+ *     verifying caches.
+ *
+ * Layout (when signing enabled): `[FRAME_BYTE][32-byte MAC][msgpackr bytes]`
+ * Layout (when signing disabled): raw msgpackr bytes (unchanged).
+ */
+const FRAME_SIGNED_V1 = 0x01;
+const MAC_LENGTH = 32; // SHA-256 output
+export class RedisCache {
+    client;
+    keyPrefix;
+    tagPrefix;
+    packr = new Packr({ moreTypes: true });
+    signingKey;
+    constructor(opts) {
+        this.client = opts.client;
+        this.keyPrefix = opts.keyPrefix ?? "";
+        this.tagPrefix = opts.tagPrefix ?? "tag:";
+        if (opts.signingKey) {
+            if (opts.signingKey.length < 32) {
+                throw new Error("RedisCache: signingKey must be at least 32 characters");
+            }
+            this.signingKey = Buffer.from(opts.signingKey, "utf8");
+        }
+    }
+    k(key) {
+        return this.keyPrefix + key;
+    }
+    t(tag) {
+        return this.keyPrefix + this.tagPrefix + tag;
+    }
+    /**
+     * Wrap raw msgpackr bytes with the F14 signed frame when signing is
+     * enabled. The MAC binds the value to the namespaced key — an
+     * attacker who steals one key's signed payload cannot replay it
+     * under a different key.
+     */
+    frame(namespacedKey, payload) {
+        if (!this.signingKey)
+            return payload;
+        const mac = createHmac("sha256", this.signingKey)
+            .update(namespacedKey)
+            .update(payload)
+            .digest();
+        return Buffer.concat([Buffer.from([FRAME_SIGNED_V1]), mac, payload]);
+    }
+    /**
+     * Unwrap a signed frame, verifying the MAC. Returns `null` (and
+     * fires a fire-and-forget delete of the offending key) on any
+     * mismatch — frame byte unrecognized, MAC truncated, MAC fails to
+     * verify, or signing was enabled but the value is unsigned (a
+     * pre-signing entry or a tampering attempt). When signing is
+     * disabled, returns the buffer as-is.
+     */
+    unframe(namespacedKey, buf) {
+        if (!this.signingKey)
+            return buf;
+        if (buf.length < 1 + MAC_LENGTH) {
+            this.dropPoisoned(namespacedKey);
+            return null;
+        }
+        if (buf[0] !== FRAME_SIGNED_V1) {
+            this.dropPoisoned(namespacedKey);
+            return null;
+        }
+        const mac = buf.subarray(1, 1 + MAC_LENGTH);
+        const payload = buf.subarray(1 + MAC_LENGTH);
+        const expected = createHmac("sha256", this.signingKey)
+            .update(namespacedKey)
+            .update(payload)
+            .digest();
+        if (mac.length !== expected.length || !timingSafeEqual(mac, expected)) {
+            this.dropPoisoned(namespacedKey);
+            return null;
+        }
+        return payload;
+    }
+    /**
+     * Best-effort delete of a poisoned entry. Run in the background so
+     * a failure (or a Redis hiccup) doesn't shadow the caller's
+     * read-returns-null semantics.
+     */
+    dropPoisoned(namespacedKey) {
+        void this.client.del(namespacedKey).catch(() => undefined);
+    }
+    async get(key) {
+        const namespacedKey = this.k(key);
+        const buf = await this.client.getBuffer(namespacedKey);
+        if (buf === null)
+            return null;
+        const unframed = this.unframe(namespacedKey, buf);
+        if (unframed === null)
+            return null;
+        return this.packr.unpack(unframed);
+    }
+    async setIfAbsent(key, value, opts = {}) {
+        const namespacedKey = this.k(key);
+        const payload = this.frame(namespacedKey, this.packr.pack(value));
+        const args = ["NX"];
+        if (opts.ttlSec !== undefined && opts.ttlSec > 0) {
+            args.push("EX", opts.ttlSec);
+        }
+        const result = await this.client.set(namespacedKey, payload, ...args);
+        // Real ioredis returns "OK" on success or null when the NX guard rejected.
+        return result === "OK";
+    }
+    async set(key, value, opts = {}) {
+        const namespacedKey = this.k(key);
+        const payload = this.frame(namespacedKey, this.packr.pack(value));
+        if (opts.ttlSec !== undefined && opts.ttlSec > 0) {
+            await this.client.set(namespacedKey, payload, "EX", opts.ttlSec);
+        }
+        else {
+            await this.client.set(namespacedKey, payload);
+        }
+        if (opts.tags && opts.tags.length > 0) {
+            for (const tag of opts.tags) {
+                const tagKey = this.t(tag);
+                await this.client.sadd(tagKey, namespacedKey);
+                // Match the value's TTL so tag bookkeeping doesn't outlive the data.
+                if (opts.ttlSec !== undefined && opts.ttlSec > 0) {
+                    await this.client.expire(tagKey, opts.ttlSec);
+                }
+            }
+        }
+    }
+    async del(key) {
+        const keys = (Array.isArray(key) ? key : [key]).map((k) => this.k(k));
+        if (keys.length === 0)
+            return;
+        await this.client.del(...keys);
+    }
+    async invalidateTag(tag) {
+        const tagKey = this.t(tag);
+        const members = await this.client.smembers(tagKey);
+        if (members.length > 0) {
+            await this.client.del(...members);
+        }
+        await this.client.del(tagKey);
+    }
+}
+//# sourceMappingURL=RedisCache.js.map

package/lib/app/services/cache/RedisCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisCache.js","sourceRoot":"","sources":["../../../../src/app/services/cache/RedisCache.ts"],"names":[],"mappings":"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"}

package/lib/app/services/cache/cached.d.ts

@@ -0,0 +1,30 @@
+import type { Cache, CacheSetOptions } from "./Cache.js";
+/**
+ * `cached(cache, key, ttlSec, fn, opts?)` — read-through cache helper.
+ *
+ * On cache hit, returns the stored value. On miss, runs `fn()`, stores the
+ * result with the supplied TTL + tags, and returns it.
+ *
+ * No promise coalescing — if N concurrent callers miss for the same key
+ * they all run `fn()` and the last write wins. Acceptable for idempotent
+ * read-through caching of expensive lookups; not safe for non-idempotent
+ * `fn()` (use a queue or distributed lock for those).
+ *
+ * `fn()` returning `undefined` skips the store step (treated as "do not
+ * cache"). `null` IS cached — it represents a known absence.
+ *
+ * @example
+ * const account = await cached(cache, `accounts:${id}`, 60, () =>
+ *   accountService.getById(id),
+ * );
+ *
+ * @example
+ * const profile = await cached(
+ *   cache, `profiles:${userId}`, 300,
+ *   () => profileService.fetch(userId),
+ *   { tags: [`user:${userId}`] },
+ * );
+ * // Later: cache.invalidateTag(`user:${userId}`) wipes everything tagged.
+ */
+export declare function cached<T>(cache: Cache, key: string, ttlSec: number, fn: () => Promise<T> | T, opts?: Omit<CacheSetOptions, "ttlSec">): Promise<T>;
+//# sourceMappingURL=cached.d.ts.map

package/lib/app/services/cache/cached.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cache/cached.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAC5B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,IAAI,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GACzC,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/lib/app/services/cache/cached.js

@@ -0,0 +1,38 @@
+/**
+ * `cached(cache, key, ttlSec, fn, opts?)` — read-through cache helper.
+ *
+ * On cache hit, returns the stored value. On miss, runs `fn()`, stores the
+ * result with the supplied TTL + tags, and returns it.
+ *
+ * No promise coalescing — if N concurrent callers miss for the same key
+ * they all run `fn()` and the last write wins. Acceptable for idempotent
+ * read-through caching of expensive lookups; not safe for non-idempotent
+ * `fn()` (use a queue or distributed lock for those).
+ *
+ * `fn()` returning `undefined` skips the store step (treated as "do not
+ * cache"). `null` IS cached — it represents a known absence.
+ *
+ * @example
+ * const account = await cached(cache, `accounts:${id}`, 60, () =>
+ *   accountService.getById(id),
+ * );
+ *
+ * @example
+ * const profile = await cached(
+ *   cache, `profiles:${userId}`, 300,
+ *   () => profileService.fetch(userId),
+ *   { tags: [`user:${userId}`] },
+ * );
+ * // Later: cache.invalidateTag(`user:${userId}`) wipes everything tagged.
+ */
+export async function cached(cache, key, ttlSec, fn, opts = {}) {
+    const hit = await cache.get(key);
+    if (hit !== null)
+        return hit;
+    const value = await fn();
+    if (value !== undefined) {
+        await cache.set(key, value, { ttlSec, tags: opts.tags });
+    }
+    return value;
+}
+//# sourceMappingURL=cached.js.map

package/lib/app/services/cache/cached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.js","sourceRoot":"","sources":["../../../../src/app/services/cache/cached.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,KAAY,EACZ,GAAW,EACX,MAAc,EACd,EAAwB,EACxB,OAAwC,EAAE;IAE1C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IAE7B,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;IACzB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/lib/app/services/cache/index.d.ts

@@ -0,0 +1,5 @@
+export type { Cache, CacheSetOptions } from "./Cache.js";
+export { cached } from "./cached.js";
+export { InMemoryCache, type InMemoryCacheOptions } from "./InMemoryCache.js";
+export { RedisCache, type RedisCacheOptions, type RedisLike } from "./RedisCache.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/app/services/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cache/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/app/services/cache/index.js

@@ -0,0 +1,4 @@
+export { cached } from "./cached.js";
+export { InMemoryCache } from "./InMemoryCache.js";
+export { RedisCache } from "./RedisCache.js";
+//# sourceMappingURL=index.js.map

package/lib/app/services/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/services/cache/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAA0C,MAAM,iBAAiB,CAAC"}

package/lib/app/services/cron/defineCron.d.ts

@@ -0,0 +1,57 @@
+import { type JobDefinition, type JobHandler } from "../jobs/defineJob.js";
+/**
+ * `defineCron({ name, schedule, handler, options? })` — schema-driven
+ * cron registration via BullMQ repeatable jobs.
+ *
+ * Cron jobs ARE jobs — they live in the same `jobRegistry` and run on the
+ * same Worker as queued jobs. The differences are ergonomic:
+ *
+ *   - One queue per process by default (`"cron"`), so the framework's
+ *     worker picks them up automatically without having to declare a
+ *     queue per cron task.
+ *   - The handler doesn't receive a meaningful payload — just the
+ *     run-context (job id, request context). Payload type is `void`.
+ *   - The schedule is expressed at the top level, not nested under
+ *     `options.schedule`.
+ *
+ * Files at `modules/<name>/cron/<cronName>.cron.ts` default-export a
+ * `defineCron(...)` call (convention enforced by `ship-api g cron`).
+ *
+ * @example
+ * import { defineCron } from "@sixthsummit/ship-api/app/services/cron";
+ *
+ * export default defineCron({
+ *   name: "purge-stale-tokens",
+ *   schedule: "0 2 * * *", // daily at 02:00 UTC
+ *   handler: async (_payload, { job }) => {
+ *     await refreshTokenService.purgeRevoked();
+ *     job.log("done");
+ *   },
+ * });
+ */
+export interface DefineCronArgs {
+    /** Unique name within the cron queue. */
+    name: string;
+    /** Cron expression (BullMQ `repeat.pattern`). */
+    schedule: string;
+    /** Job handler — payload arg is `void` because cron jobs don't carry one. */
+    handler: JobHandler<void, unknown>;
+    /**
+     * Override the queue name. Default `"cron"` so a single Worker handles
+     * every cron task in the process. Set when you want a dedicated queue
+     * (e.g., low-priority cleanup vs high-priority billing).
+     */
+    queue?: string;
+    /** Optional timezone for the cron pattern (defaults to UTC). */
+    tz?: string;
+    /** BullMQ JobsOptions applied to each scheduled run. */
+    defaultJobOptions?: JobDefinition["options"] extends infer O ? O extends {
+        defaultJobOptions?: infer J;
+    } ? J : undefined : undefined;
+}
+/** Default queue name for cron tasks. */
+export declare const CRON_QUEUE = "cron";
+export declare function defineCron(args: DefineCronArgs, register?: {
+    add: (def: JobDefinition) => void;
+} | false): JobDefinition<void, unknown>;
+//# sourceMappingURL=defineCron.d.ts.map

package/lib/app/services/cron/defineCron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCron.d.ts","sourceRoot":"","sources":["../../../../src/app/services/cron/defineCron.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,UAAU,EAGhB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,SAAS,MAAM,CAAC,GACxD,CAAC,SAAS;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAA;KAAE,GACvC,CAAC,GACD,SAAS,GACX,SAAS,CAAC;CACf;AAED,yCAAyC;AACzC,eAAO,MAAM,UAAU,SAAS,CAAC;AAEjC,wBAAgB,UAAU,CACxB,IAAI,EAAE,cAAc,EACpB,QAAQ,GAAE;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAA;CAAE,GAAG,KAAmB,GACpE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAa9B"}