@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/esm/rate-limit/index.js

@@ -2,23 +2,48 @@ import { RateLimiterMemory, RateLimiterRedis } from 'rate-limiter-flexible';
 import { errorResponse } from '../common/response.js';
 import { TooManyRequestsError } from '../common/errors.js';
 import { silentLogger } from '../logging/index.js';
-/** Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. */
+import { encodeKeyPart } from '../cache/keyspace.js';
+import { RATE_LIMIT_PURPOSE } from './keys.js';
+export * from './keys.js';
+/**
+ * Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. Its
+ * keys come from the keyspace; pass already-encoded keys (see {@link limiterKey}) to `consume`.
+ *
+ * @param options Points, window, keyspace and scope.
+ * @returns The limiter.
+ * @example const limiter = createLimiter({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis });
+ */
 export function createLimiter(options) {
-    const memory = new RateLimiterMemory({ keyPrefix: options.keyPrefix, points: options.points, duration: options.durationSec, blockDuration: options.blockDurationSec ?? 0 });
+    const keyPrefix = options.keyspace.key(RATE_LIMIT_PURPOSE, options.scope);
+    const memory = new RateLimiterMemory({ keyPrefix, points: options.points, duration: options.durationSec, blockDuration: options.blockDurationSec ?? 0 });
     if (!options.redis)
         return memory;
     return new RateLimiterRedis({
         storeClient: options.redis,
-        keyPrefix: options.keyPrefix,
+        keyPrefix,
         points: options.points,
         duration: options.durationSec,
         blockDuration: options.blockDurationSec ?? 0,
         insuranceLimiter: memory,
     });
 }
+/**
+ * Encodes a raw limiter key (user id, IP …) so it cannot add segments to the limiter's Redis key.
+ *
+ * @param raw Raw identifier.
+ * @returns The encoded key part.
+ * @example limiter.consume(limiterKey(req.ip))
+ */
+export const limiterKey = (raw) => encodeKeyPart(raw);
 /**
  * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
- * For in-service checks such as per-identifier login throttling.
+ * For in-service checks such as per-identifier sign-in throttling.
+ *
+ * @param limiter Limiter from {@link createLimiter}.
+ * @param key Encoded key (see {@link limiterKey}).
+ * @param message Optional public message for the 429.
+ * @throws TooManyRequestsError when the limit is exhausted; rethrows limiter failures.
+ * @example await consumeOrThrow(limiter, limiterKey(userId));
  */
 export async function consumeOrThrow(limiter, key, message) {
     try {
@@ -30,13 +55,23 @@ export async function consumeOrThrow(limiter, key, message) {
         throw rejection;
     }
 }
+/**
+ * Express middleware that consumes one point per request. Sets `X-RateLimit-Limit` and
+ * `X-RateLimit-Remaining`; when exhausted answers 429 `RATE_LIMITED` with `Retry-After` (seconds).
+ * Fails open: a limiter error (not a rejection) is logged and the request continues.
+ *
+ * @param options Limiter options and `keyOf` (default user id, else client IP).
+ * @returns The middleware.
+ * @example router.post('/sessions', rateLimitMiddleware({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis }), handler);
+ */
 export function rateLimitMiddleware(options) {
     const limiter = createLimiter(options);
     const logger = options.logger ?? silentLogger;
     const keyOf = options.keyOf ?? ((req) => req.user?.id ?? req.ip ?? 'unknown');
+    const scope = options.scope;
     return async (req, res, next) => {
         try {
-            const result = await limiter.consume(keyOf(req));
+            const result = await limiter.consume(limiterKey(keyOf(req)));
             res.setHeader('X-RateLimit-Limit', options.points);
             res.setHeader('X-RateLimit-Remaining', result.remainingPoints);
             next();
@@ -44,7 +79,7 @@ export function rateLimitMiddleware(options) {
         catch (rejection) {
             const ms = rejection?.msBeforeNext;
             if (typeof ms !== 'number') {
-                logger.error('Rate limiter failure; allowing request', { keyPrefix: options.keyPrefix, error: String(rejection) });
+                logger.error('Rate limiter failure; allowing request', { scope, error: String(rejection) });
                 next();
                 return;
             }

package/dist/esm/rate-limit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAA4B,MAAM,uBAAuB,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,cAAc,WAAW,CAAC;AAgB1B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,OAAyB;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC,CAAC;IACzJ,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,IAAI,gBAAgB,CAAC;QAC1B,WAAW,EAAE,OAAO,CAAC,KAAK;QAC1B,SAAS;QACT,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,WAAW;QAC7B,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC;QAC5C,gBAAgB,EAAE,MAAM;KACzB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA4B,EAAE,GAAW,EAAE,OAAgB;IAC9F,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,IAAI,OAAQ,SAAuC,EAAE,YAAY,KAAK,QAAQ;YAAE,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACxH,MAAM,SAAS,CAAC;IAClB,CAAC;AACH,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,SAAS,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAE5B,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAiB,EAAE;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC7D,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACnD,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;YAC/D,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,EAAE,GAAI,SAAuC,EAAE,YAAY,CAAC;YAClE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBAC5F,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACnD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,4CAA4C,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/rate-limit/keys.js

@@ -0,0 +1,43 @@
+import { ConfigError } from '../config/index.js';
+import { sensitivePart } from '../cache/keyspace.js';
+/**
+ * Rate-limit key builder and the sliding-window limiter contract. Dependency-free (exported from the
+ * package root as well as `/rate-limit`); the consuming service implements the sliding window.
+ */
+/** Purpose segment for every rate-limit key: `{prefix}rl:{scope}:…`. */
+export const RATE_LIMIT_PURPOSE = 'rl';
+const SCOPE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DIMENSIONS = ['ip', 'userId', 'email', 'host', 'route'];
+const DIMENSION_SEGMENT = { ip: 'ip', userId: 'user', email: 'email', host: 'host', route: 'route' };
+function dimensionValue(name, raw) {
+    const value = raw.trim();
+    if (name === 'email')
+        return sensitivePart(value.toLowerCase());
+    if (name === 'host')
+        return value.toLowerCase();
+    return value;
+}
+/**
+ * Builds `{prefix}rl:{scope}[:ip:{ip}][:user:{id}][:email:{hash}][:host:{host}][:route:{route}]`.
+ *
+ * @param keyspace The service keyspace.
+ * @param input Scope plus at least one dimension.
+ * @returns The rate-limit key.
+ * @throws ConfigError when no dimension is given or the scope is invalid.
+ * @example rateLimitKey(ks, { scope: 'sign-in', ip: req.ip, email: body.email })
+ */
+export function rateLimitKey(keyspace, input) {
+    if (!SCOPE_PATTERN.test(input.scope))
+        throw new ConfigError(`Rate-limit scope "${input.scope}" must be lower-case kebab-case`);
+    const parts = [];
+    for (const name of DIMENSIONS) {
+        const raw = input[name];
+        if (raw === undefined || raw.trim() === '')
+            continue;
+        parts.push(DIMENSION_SEGMENT[name], dimensionValue(name, raw));
+    }
+    if (!parts.length)
+        throw new ConfigError(`Rate-limit key "${input.scope}" needs at least one of ${DIMENSIONS.join(', ')}`);
+    return keyspace.key(RATE_LIMIT_PURPOSE, input.scope, ...parts);
+}
+//# sourceMappingURL=keys.js.map

package/dist/esm/rate-limit/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/rate-limit/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAwD,MAAM,sBAAsB,CAAC;AAE3G;;;GAGG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAgBvC,MAAM,aAAa,GAAG,4BAA4B,CAAC;AACnD,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAGvE,MAAM,iBAAiB,GAA8B,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAEhI,SAAS,cAAc,CAAC,IAAe,EAAE,GAAW;IAClD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IAChD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAuB,EAAE,KAAwB;IAC5E,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,qBAAqB,KAAK,CAAC,KAAK,iCAAiC,CAAC,CAAC;IAC/H,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACrD,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,WAAW,CAAC,mBAAmB,KAAK,CAAC,KAAK,2BAA2B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3H,OAAO,QAAQ,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC;AACjE,CAAC"}

package/dist/esm/socket/index.js

@@ -1,21 +1,26 @@
+import { createAdapter } from '@socket.io/redis-adapter';
 import { Server } from 'socket.io';
-import { verifyIdentityHeaders } from '../identity/index.js';
+import { assertGatewaySecret, verifyGatewayIdentity } from '../identity/index.js';
 import { silentLogger } from '../logging/index.js';
+import { verifySocketTicket } from './ticket.js';
+export * from './ticket.js';
+/** Name of the private room every connection of `userId` joins. */
 export const userRoom = (userId) => `user:${userId}`;
-export function createSocketServer(httpServer, options) {
-    const logger = options.logger ?? silentLogger;
+/** Builds the server: authenticate every handshake, then join only server-derived rooms. */
+function buildServer(httpServer, core) {
+    const { logger } = core;
     const io = new Server(httpServer, {
-        path: options.path,
-        cors: { origin: options.corsOrigins?.length ? options.corsOrigins : false, credentials: true },
-        ...(options.adapter ? { adapter: options.adapter } : {}),
-        ...options.serverOptions,
+        path: core.path,
+        cors: core.cors,
+        ...(core.adapter ? { adapter: core.adapter } : {}),
+        ...core.serverOptions,
     });
     io.use(async (socket, next) => {
         try {
-            const user = await options.authenticate(socket);
-            if (!user)
+            const identity = await core.authenticate(socket);
+            if (!identity)
                 return next(new Error('Authentication failed'));
-            socket.data.user = user;
+            socket.data.identity = identity;
             next();
         }
         catch (error) {
@@ -24,11 +29,12 @@ export function createSocketServer(httpServer, options) {
         }
     });
     io.on('connection', (socket) => {
-        const user = socket.data.user;
-        const rooms = options.rooms ? options.rooms(user) : [userRoom(user.id)];
+        const identity = socket.data.identity;
+        const userId = core.userIdOf(identity);
+        const rooms = core.rooms(identity);
         void socket.join(rooms);
-        logger.debug('Socket connected', { userId: user.id, rooms });
-        socket.on('disconnect', (reason) => logger.debug('Socket disconnected', { userId: user.id, reason }));
+        logger.debug('Socket connected', { userId, rooms });
+        socket.on('disconnect', (reason) => logger.debug('Socket disconnected', { userId, reason }));
     });
     return {
         io,
@@ -37,11 +43,100 @@ export function createSocketServer(httpServer, options) {
         close: () => new Promise((resolve) => { io.close(() => resolve()); }),
     };
 }
-/** Trusts the gateway-signed identity headers forwarded on the WebSocket upgrade request. */
-export function gatewaySocketAuth(secret) {
+/**
+ * Creates a Socket.IO server that authenticates every connection and joins it only to server-derived rooms.
+ * The verified user is in `socket.data.identity`.
+ *
+ * @example const sockets = createSocketServer(httpServer, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
+export function createSocketServer(httpServer, options) {
+    return buildServer(httpServer, {
+        path: options.path,
+        cors: { origin: options.corsOrigins?.length ? options.corsOrigins : false, credentials: true },
+        adapter: options.adapter,
+        serverOptions: options.serverOptions,
+        logger: options.logger ?? silentLogger,
+        authenticate: options.authenticate,
+        userIdOf: (user) => user.id,
+        rooms: options.rooms ?? ((user) => [userRoom(user.id)]),
+    });
+}
+/**
+ * Trusts the gateway-signed (v2) identity headers forwarded on the WebSocket upgrade request. The gateway
+ * signs the upgrade as `GET <handshake path>` (query ignored).
+ *
+ * @param options The shared secret (at least 32 characters) and the app's identity protocol.
+ * @returns An `authenticate` function for {@link createSocketServer}.
+ * @example createSocketServer(server, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
+export function gatewaySocketAuth(options) {
+    const secret = assertGatewaySecret(options.secret);
     return (socket) => {
-        const result = verifyIdentityHeaders(socket.handshake.headers, secret);
+        const result = verifyGatewayIdentity({
+            headers: socket.handshake.headers, method: 'GET', path: socket.handshake.url, secret, protocol: options.protocol,
+        });
         return result.status === 'authenticated' ? result.user : null;
     };
 }
+/**
+ * The handshake check on its own (testable without a server): verifies the ticket from
+ * `socket.handshake.auth.ticket`, then the browser origin against `allowedOrigins(claims)`, then
+ * single use.
+ *
+ * @param options Ticket keys, audience, origin rule, replay check and rejection hook.
+ * @returns `authenticate(socket)` resolving to the claims, or null when refused.
+ */
+export function createTicketHandshake(options) {
+    const reject = (reason, userId, origin) => {
+        options.onRejected?.({ reason, userId, path: options.path, origin });
+        return null;
+    };
+    return async (socket) => {
+        const origin = typeof socket.handshake.headers.origin === 'string' ? socket.handshake.headers.origin : null;
+        const auth = (socket.handshake.auth ?? {});
+        const result = verifySocketTicket(auth.ticket, options);
+        if (!result.ok)
+            return reject(result.reason, null, origin);
+        const { claims } = result;
+        if (origin ? !(await options.allowedOrigins(claims)).includes(origin) : !options.allowMissingOrigin) {
+            return reject('origin_not_allowed', claims.userId, origin);
+        }
+        if (options.isFirstUse && !(await options.isFirstUse(claims)))
+            return reject('replayed', claims.userId, origin);
+        return claims;
+    };
+}
+/**
+ * Creates a Socket.IO server whose clients authenticate with a short-lived ticket
+ * (`io(url, { path, auth: (cb) => getTicket().then((ticket) => cb({ ticket })) })`). Each connection
+ * auto-joins `user:{userId}`; the verified claims are in `socket.data.identity` for later room checks
+ * with `canJoinScopeRoom`.
+ *
+ * @param options HTTP server, path, ticket keys, origin rule, Redis + keyspace, rejection hook.
+ * @returns The emitter.
+ * @example createTicketSocketServer({ httpServer, path: '/ws', secret, domain, audience: 'admin-app', redis, keyspace, allowedOrigins: () => origins, onRejected })
+ */
+export function createTicketSocketServer(options) {
+    const { redis, keyspace } = options;
+    if (redis && !keyspace)
+        throw new Error('createTicketSocketServer: a keyspace is required with redis');
+    const isFirstUse = redis && keyspace
+        ? async (claims) => {
+            const ttl = Math.max(1, claims.exp - Math.floor(Date.now() / 1000));
+            return (await redis.set(keyspace.key('socket-ticket', claims.jti), '1', 'EX', ttl, 'NX')) === 'OK';
+        }
+        : undefined;
+    const authenticate = createTicketHandshake({ ...options, isFirstUse });
+    return buildServer(options.httpServer, {
+        path: options.path,
+        // Browsers do not apply CORS to WebSocket upgrades; the per-ticket origin check above is the real gate.
+        cors: { origin: true, credentials: false },
+        adapter: redis && keyspace ? createAdapter(redis, redis.duplicate(), { key: keyspace.key('socket-io') }) : undefined,
+        serverOptions: options.serverOptions,
+        logger: options.logger ?? silentLogger,
+        authenticate,
+        userIdOf: (claims) => claims.userId,
+        rooms: (claims) => [userRoom(claims.userId), ...(options.rooms?.(claims) ?? [])],
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/socket/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAE,MAAM,EAAmC,MAAM,WAAW,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAyB,MAAM,sBAAsB,CAAC;AACzG,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAoF,MAAM,aAAa,CAAC;AAEnI,cAAc,aAAa,CAAC;AA0B5B,mEAAmE;AACnE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,QAAQ,MAAM,EAAE,CAAC;AAc7D,4FAA4F;AAC5F,SAAS,WAAW,CAAI,UAAsB,EAAE,IAAmB;IACjE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE;QAChC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,IAAI,CAAC,aAAa;KACtB,CAAC,CAAC;IAEH,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACjD,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;YAC/D,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAChC,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YACnF,IAAI,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;QAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAa,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACpD,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/F,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,EAAE;QACF,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QACzF,UAAU,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3E,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAsB,EAAE,OAA4B;IACrF,OAAO,WAAW,CAAW,UAAU,EAAE;QACvC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;QAC9F,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,YAAY;QACtC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE;QAC3B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;KACxD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuD;IACvF,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,CAAC,MAAc,EAAmB,EAAE;QACzC,MAAM,MAAM,GAAG,qBAAqB,CAAC;YACnC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,OAAiC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3I,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,CAAC,CAAC;AACJ,CAAC;AA+BD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACnE,MAAM,MAAM,GAAG,CAAC,MAA6B,EAAE,MAAqB,EAAE,MAAqB,EAAE,EAAE;QAC7F,OAAO,CAAC,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5G,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAyB,CAAC;QACnE,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3D,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAC1B,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YACpG,OAAO,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACpC,IAAI,KAAK,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACvG,MAAM,UAAU,GAAG,KAAK,IAAI,QAAQ;QAClC,CAAC,CAAC,KAAK,EAAE,MAA0B,EAAE,EAAE;YACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACpE,OAAO,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC;QACrG,CAAC;QACD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,YAAY,GAAG,qBAAqB,CAAC,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IACvE,OAAO,WAAW,CAAqB,OAAO,CAAC,UAAU,EAAE;QACzD,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,wGAAwG;QACxG,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE;QAC1C,OAAO,EAAE,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;QACpH,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,YAAY;QACtC,YAAY;QACZ,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM;QACnC,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;KACjF,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/socket/ticket.js

@@ -0,0 +1,117 @@
+import { hasPermission } from '../access/index.js';
+import { hmacSha256, safeEqual } from '../common/crypto.js';
+import { newId } from '../common/id.js';
+/**
+ * Short-lived socket handshake tickets. The browser cannot send its in-memory access token on a
+ * WebSocket upgrade header, so it asks the API for a ticket (≤ 60 s) and passes it in the Socket.IO
+ * `auth` payload. A ticket is `v1.<base64url claims>.<base64url HMAC-SHA256>`, signed over a domain
+ * separator so a ticket minted for another app or purpose never verifies here.
+ *
+ * Dependency-free (no socket.io), so the issuer can sign tickets without the socket stack.
+ */
+/** Longest allowed ticket lifetime (and the default), in seconds. */
+export const SOCKET_TICKET_MAX_TTL_SECONDS = 60;
+/** Shortest accepted signing secret. */
+export const MIN_SOCKET_TICKET_SECRET_LENGTH = 32;
+const VERSION = 'v1';
+/** Tolerated clock skew for `iat` in the future, in seconds. */
+const MAX_FUTURE_SKEW_SECONDS = 5;
+function assertKey(options) {
+    if (!options.secret || options.secret.length < MIN_SOCKET_TICKET_SECRET_LENGTH) {
+        throw new Error(`Socket ticket secret must be at least ${MIN_SOCKET_TICKET_SECRET_LENGTH} characters`);
+    }
+    if (!options.domain)
+        throw new Error('Socket tickets need a domain separator');
+}
+const signature = (options, body) => Buffer.from(hmacSha256(options.secret, `${options.domain}\n${VERSION}.${body}`), 'hex').toString('base64url');
+const nowSeconds = (options) => Math.floor((options.now?.() ?? new Date()).getTime() / 1000);
+/**
+ * Signs a ticket.
+ *
+ * @param input User, audience, scopes and permissions.
+ * @param options Secret, domain separator and `ttlSeconds` (1–60, default 60).
+ * @returns The ticket string.
+ * @example signSocketTicket({ userId, aud: 'admin-app', scopes: { tenant: [tenantId] }, permissions }, { secret, domain: 'myapp-socket-ticket:v1' })
+ */
+export function signSocketTicket(input, options) {
+    assertKey(options);
+    const ttl = options.ttlSeconds ?? SOCKET_TICKET_MAX_TTL_SECONDS;
+    if (!Number.isInteger(ttl) || ttl < 1 || ttl > SOCKET_TICKET_MAX_TTL_SECONDS) {
+        throw new RangeError(`Socket ticket TTL must be 1–${SOCKET_TICKET_MAX_TTL_SECONDS} seconds`);
+    }
+    if (!input.userId || !input.aud)
+        throw new RangeError('Socket tickets need a user id and an audience');
+    const iat = nowSeconds(options);
+    const claims = {
+        userId: input.userId,
+        aud: input.aud,
+        scopes: input.scopes ?? {},
+        permissions: input.permissions ?? [],
+        isSuperAdmin: input.isSuperAdmin === true,
+        jti: newId(),
+        iat,
+        exp: iat + ttl,
+    };
+    const body = Buffer.from(JSON.stringify(claims)).toString('base64url');
+    return `${VERSION}.${body}.${signature(options, body)}`;
+}
+function parseClaims(body) {
+    try {
+        const c = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        const valid = typeof c.userId === 'string' && typeof c.aud === 'string' && typeof c.jti === 'string'
+            && Number.isInteger(c.iat) && Number.isInteger(c.exp) && Array.isArray(c.permissions)
+            && !!c.scopes && typeof c.scopes === 'object' && typeof c.isSuperAdmin === 'boolean';
+        return valid ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verifies a ticket's signature, domain, lifetime and audience. Never throws for a bad ticket.
+ *
+ * @param ticket The string from the handshake.
+ * @param options Secret, domain separator and the accepted audience(s).
+ * @returns The claims, or the rejection reason.
+ * @example const result = verifySocketTicket(socket.handshake.auth.ticket, { secret, domain, audience: 'admin-app' });
+ */
+export function verifySocketTicket(ticket, options) {
+    assertKey(options);
+    if (typeof ticket !== 'string' || !ticket)
+        return { ok: false, reason: 'missing' };
+    const parts = ticket.split('.');
+    if (parts.length !== 3 || parts[0] !== VERSION || !parts[1] || !parts[2])
+        return { ok: false, reason: 'malformed' };
+    if (!safeEqual(parts[2], signature(options, parts[1])))
+        return { ok: false, reason: 'bad_signature' };
+    const claims = parseClaims(parts[1]);
+    if (!claims)
+        return { ok: false, reason: 'malformed' };
+    const now = nowSeconds(options);
+    if (claims.exp <= now || claims.exp - claims.iat > SOCKET_TICKET_MAX_TTL_SECONDS || claims.iat > now + MAX_FUTURE_SKEW_SECONDS) {
+        return { ok: false, reason: 'expired' };
+    }
+    const audiences = typeof options.audience === 'string' ? [options.audience] : options.audience;
+    if (!audiences.includes(claims.aud))
+        return { ok: false, reason: 'wrong_audience' };
+    return { ok: true, claims };
+}
+/** Name of the room for one scope id, e.g. `tenant:01J…`. */
+export const scopeRoom = (scope, scopeId) => `${scope}:${scopeId}`;
+/**
+ * True when the ticket holder may join the room of `scopeId` in `scope`: the id is in the ticket's scope
+ * ids (or the holder is a super admin) and, when given, the holder has `permission`.
+ *
+ * @param claims Verified ticket claims.
+ * @param scope Scope name, e.g. `tenant`.
+ * @param scopeId The id whose room is requested.
+ * @param permission Permission the room needs (optional).
+ * @example canJoinScopeRoom(claims, 'tenant', tenantId, 'widgets.view')
+ */
+export function canJoinScopeRoom(claims, scope, scopeId, permission) {
+    const inScope = claims.isSuperAdmin || (claims.scopes[scope] ?? []).includes(scopeId);
+    if (!inScope || !scopeId)
+        return false;
+    return permission ? hasPermission(claims, permission) : true;
+}
+//# sourceMappingURL=ticket.js.map

package/dist/esm/socket/ticket.js.map

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

package/dist/esm/testing/index.js

@@ -1,5 +1,5 @@
 import { newId } from '../common/id.js';
-import { signIdentityHeaders } from '../identity/index.js';
+import { signedIdentityHeaders } from '../identity/index.js';
 import { buildEnvelope } from '../messaging/envelope.js';
 /** A logger spy: records every line (level, message, meta) so tests can assert on log context. */
 export class RecordingLogger {
@@ -13,24 +13,26 @@ export class RecordingLogger {
 export function makeAuthUser(overrides = {}) {
     return { id: newId(), email: 'user@example.com', roles: [], permissions: [], scopes: {}, attrs: {}, ...overrides };
 }
-/** Gateway-signed identity headers for route tests (use with supertest `.set()`). */
-export function identityHeaders(user, secret) {
-    return signIdentityHeaders(user, secret);
+/**
+ * Gateway-signed (v2) identity headers for route tests (use with supertest `.set()`). The method and path
+ * must match the request the test sends.
+ *
+ * @example request(app).get('/v1/items').set(identityHeaders({ user, secret, protocol, method: 'GET', path: '/v1/items' }));
+ */
+export function identityHeaders(input) {
+    return signedIdentityHeaders(input);
 }
-/** Records everything published/sent so tests can assert on events, commands and direct queue sends. */
+/** Records everything published/sent so tests can assert on events, commands, queue sends and delayed sends. */
 export class RecordingBus {
-    source;
     events = [];
     commands = [];
     queued = [];
+    delayed = [];
     failWith = null;
-    constructor(source = 'test') {
-        this.source = source;
-    }
-    async publish(type, data, meta) {
+    async publish(routingKey, data, meta) {
         if (this.failWith)
             throw this.failWith;
-        const envelope = buildEnvelope(type, data, this.source, meta);
+        const envelope = buildEnvelope(routingKey, data, meta);
         this.events.push(envelope);
         return envelope;
     }
@@ -42,7 +44,7 @@ export class RecordingBus {
     async send(command, data, meta) {
         if (this.failWith)
             throw this.failWith;
-        const envelope = buildEnvelope(command, data, this.source, meta);
+        const envelope = buildEnvelope(command, data, meta);
         this.commands.push(envelope);
         return envelope;
     }
@@ -56,11 +58,18 @@ export class RecordingBus {
             throw this.failWith;
         this.queued.push({ queue, payload, options });
     }
-    eventsOfType(type) {
-        return this.events.filter((e) => e.type === type);
+    async scheduleDelayed(queue, payload, delayMs, options = {}) {
+        if (this.failWith)
+            throw this.failWith;
+        this.delayed.push({ queue, payload, delayMs, options });
+    }
+    /** Published events with this routing key. */
+    eventsOfType(routingKey) {
+        return this.events.filter((e) => e.routingKey === routingKey);
     }
+    /** Sent commands with this name. */
     commandsOfType(command) {
-        return this.commands.filter((e) => e.type === command);
+        return this.commands.filter((e) => e.routingKey === command);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/esm/testing/index.js.map

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

package/dist/types/access/index.d.ts

@@ -7,11 +7,16 @@ import type { AuthUser } from '../types/index.js';
  * wildcards: `*` grants everything; `media.*` grants any permission starting with `media.`.
  */
 export declare const WILDCARD_PERMISSION = "*";
-/** True when the user holds at least one of `required`. */
-export declare function hasPermission(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
-export declare function hasAllPermissions(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
+type PermissionHolder = Pick<AuthUser, 'permissions' | 'isSuperAdmin'>;
+/** True when the user holds at least one of `required`. A super admin holds every permission. */
+export declare function hasPermission(user: PermissionHolder | null | undefined, ...required: string[]): boolean;
+/** True when the user holds every one of `required`. A super admin holds every permission. */
+export declare function hasAllPermissions(user: PermissionHolder | null | undefined, ...required: string[]): boolean;
+/** True when the user has at least one of `roles`. Prefer permission checks; roles are coarse. */
 export declare function hasRole(user: Pick<AuthUser, 'roles'> | null | undefined, ...roles: string[]): boolean;
+/** Returns the user, or throws UnauthorizedError (401) when there is none. */
 export declare function requireUser(user: AuthUser | null | undefined): AuthUser;
+/** Returns the user when they hold any of `required` (super admin always does); throws 401/403 otherwise. */
 export declare function assertPermission(user: AuthUser | null | undefined, ...required: string[]): AuthUser;
 /** IDs the user may act on within a scope (e.g. profiles they are a member of). */
 export declare function scopeIds(user: Pick<AuthUser, 'scopes'> | null | undefined, scope: string): string[];
@@ -47,4 +52,5 @@ export type OwnerFilter = {
  * otherwise the caller's own scope IDs (possibly empty → return nothing).
  */
 export declare function ownerFilter(user: AuthUser | null | undefined, scope: string, bypassPermission?: string): OwnerFilter;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/types/access/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAOvC,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGpH;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGxH;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAErG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAGvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,CAInG;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKlI;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAK5I;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASxH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGzH;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,CAIpH"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAOvC,KAAK,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC;AAEvE,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAIvG;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAI3G;AAED,kGAAkG;AAClG,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAErG;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAGvE;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,CAInG;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKlI;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAK5I;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASxH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGzH;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,CAIpH"}