@shaferllc/keel 0.36.0 → 0.59.0

package/dist/core/broker.js

@@ -0,0 +1,602 @@
+/**
+ * A service broker — a Moleculer-style backbone for service-oriented code.
+ * Register *services* (a name plus a bag of `actions` and `events`), then reach
+ * them by string name: `broker.call("users.get", { id })` runs an action and
+ * returns its result; `broker.emit("user.created", user)` fans an event out to
+ * every service that listens. Actions receive a `Context` and can call *other*
+ * actions or emit events through it, so a request threads its `meta` (auth,
+ * trace ids) all the way down.
+ *
+ *   const broker = new Broker();
+ *   broker.createService({
+ *     name: "math",
+ *     actions: {
+ *       add: (ctx: Context<{ a: number; b: number }>) => ctx.params.a + ctx.params.b,
+ *     },
+ *   });
+ *   await broker.start();
+ *   await broker.call("math.add", { a: 2, b: 3 });   // 5
+ *
+ * Like the queue and Redis layers, clustering lives behind a pluggable seam: the
+ * default `LocalTransporter` is a single-node no-op, so the core imports no
+ * network client and runs on Node and the edge. Swap in a real `Transporter`
+ * (NATS, Redis, TCP) to span processes — the call/emit API doesn't change.
+ */
+import { Logger } from "./logger.js";
+import { ValidationException } from "./exceptions.js";
+/* ----------------------------- schema helpers ----------------------------- */
+function toArray(x) {
+    return x == null ? [] : Array.isArray(x) ? x : [x];
+}
+/** Chain two lifecycle hooks into one that awaits both, in order. */
+function chain(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return async function (...args) {
+        await a.apply(this, args);
+        await b.apply(this, args);
+    };
+}
+const LIFECYCLE = new Set(["created", "started", "stopped", "merged"]);
+/** Merge one schema over a base, following Moleculer's per-property rules. */
+function mergeSchema(base, ext) {
+    const out = { ...base };
+    for (const key of Object.keys(ext)) {
+        const v = ext[key];
+        if (v === undefined || key === "mixins")
+            continue;
+        if (key === "name" || key === "version") {
+            out[key] = v;
+        }
+        else if (key === "settings" || key === "metadata" || key === "actions" || key === "methods" || key === "events") {
+            out[key] = { ...(base[key] ?? {}), ...v };
+        }
+        else if (key === "hooks") {
+            out[key] = {
+                before: { ...(base.hooks?.before ?? {}), ...(v.before ?? {}) },
+                after: { ...(base.hooks?.after ?? {}), ...(v.after ?? {}) },
+                error: { ...(base.hooks?.error ?? {}), ...(v.error ?? {}) },
+            };
+        }
+        else if (key === "dependencies") {
+            out[key] = [...new Set([...toArray(base[key]), ...toArray(v)])];
+        }
+        else if (LIFECYCLE.has(key)) {
+            out[key] = chain(base[key], v);
+        }
+        else {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+/** Flatten a schema's `mixins` into it — this schema always wins on conflict. */
+function applyMixins(schema) {
+    if (!schema.mixins?.length)
+        return schema;
+    // Fold mixins last→first so the first mixin ends up highest-priority among
+    // them; the service's own schema is applied last, so it wins overall.
+    let merged = {};
+    for (const mixin of [...schema.mixins].reverse()) {
+        merged = mergeSchema(merged, applyMixins(mixin));
+    }
+    const { mixins: _drop, ...own } = schema;
+    return mergeSchema(merged, own);
+}
+/** A live service instance. Bound as `this` inside handlers, methods, and hooks. */
+export class Service {
+    name;
+    version;
+    /** Versioned, dotted prefix — `"users"` or `"v2.users"`. */
+    fullName;
+    settings;
+    metadata;
+    /** Services that must exist before this one's `started` hook runs. */
+    dependencies;
+    broker;
+    logger;
+    /** Internal callers for this service's own actions — `this.actions.foo(params)`. */
+    actions = {};
+    /** @internal normalized actions, keyed by local (unprefixed) name. */
+    _actions = new Map();
+    /** @internal normalized event listeners, keyed by pattern. */
+    _events = new Map();
+    /** @internal normalized service-level hooks. */
+    _hooks;
+    constructor(broker, schema) {
+        this.name = schema.name;
+        this.version = schema.version;
+        this.fullName = schema.version != null ? `v${schema.version}.${schema.name}` : schema.name;
+        this.settings = schema.settings ?? {};
+        this.metadata = schema.metadata ?? {};
+        this.dependencies = toArray(schema.dependencies);
+        this.broker = broker;
+        this.logger = broker.logger.child({ service: this.fullName });
+        // Bind methods first so actions/hooks can call them via `this`.
+        for (const [key, fn] of Object.entries(schema.methods ?? {})) {
+            this[key] = fn.bind(this);
+        }
+        for (const [name, entry] of Object.entries(schema.actions ?? {})) {
+            const def = typeof entry === "function" ? { handler: entry } : entry;
+            this._actions.set(name, {
+                name,
+                handler: def.handler.bind(this),
+                visibility: def.visibility ?? "published",
+                timeout: def.timeout,
+                params: def.params,
+                cache: def.cache,
+                hooks: {
+                    before: toArray(def.hooks?.before).map((f) => f.bind(this)),
+                    after: toArray(def.hooks?.after).map((f) => f.bind(this)),
+                    error: toArray(def.hooks?.error).map((f) => f.bind(this)),
+                },
+            });
+        }
+        for (const [pattern, entry] of Object.entries(schema.events ?? {})) {
+            const def = typeof entry === "function" ? { handler: entry } : entry;
+            this._events.set(pattern, { handler: def.handler.bind(this), group: def.group ?? this.name });
+        }
+        const bindHookMap = (m) => {
+            const out = {};
+            for (const [key, fns] of Object.entries(m ?? {}))
+                out[key] = toArray(fns).map((f) => f.bind(this));
+            return out;
+        };
+        this._hooks = {
+            before: bindHookMap(schema.hooks?.before),
+            after: bindHookMap(schema.hooks?.after),
+            error: bindHookMap(schema.hooks?.error),
+        };
+        this._schema = schema;
+    }
+    /** Wait until the named service(s) are registered on this broker. */
+    waitForServices(deps, timeout, interval) {
+        return this.broker.waitForServices(deps, timeout, interval);
+    }
+    /** @internal the merged schema, for lifecycle hooks. */
+    _schema;
+}
+/* --------------------------------- errors --------------------------------- */
+/** Thrown by `call` when no action matches the requested name. */
+export class ServiceNotFoundError extends Error {
+    action;
+    constructor(action) {
+        super(`No action named "${action}" is registered.`);
+        this.action = action;
+        this.name = "ServiceNotFoundError";
+    }
+}
+/** Thrown by `call` when an action exceeds its timeout. */
+export class RequestTimeoutError extends Error {
+    action;
+    timeout;
+    constructor(action, timeout) {
+        super(`Action "${action}" timed out after ${timeout}ms.`);
+        this.action = action;
+        this.timeout = timeout;
+        this.name = "RequestTimeoutError";
+    }
+}
+/** The default transporter — a single node, nothing to connect. */
+export class LocalTransporter {
+    async connect(_broker) { }
+    async disconnect() { }
+}
+/* --------------------------------- broker --------------------------------- */
+/** Match a subscription pattern (with optional `*`/`**`/`?` globs) to an event name. */
+function eventMatches(pattern, event) {
+    if (pattern === event)
+        return true;
+    if (!/[*?]/.test(pattern))
+        return false;
+    // Escape regex specials (but not `*`/`?`), then map globs: `**` spans dots, `*`
+    // a single segment, `?` one non-dot char. `user.*` → one level; `user.**` →
+    // any depth; `user.??eated` → a fixed-width name.
+    const rx = new RegExp("^" +
+        pattern
+            .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+            .replace(/\*\*/g, ".*")
+            .replace(/\*/g, "[^.]*")
+            .replace(/\?/g, "[^.]") +
+        "$");
+    return rx.test(event);
+}
+/** Build a cache key from an action name and its params (optionally a subset). */
+function cacheKey(action, params, keys) {
+    let keyed = params;
+    if (keys && params && typeof params === "object") {
+        const picked = {};
+        for (const k of keys)
+            picked[k] = params[k];
+        keyed = picked;
+    }
+    return `${action}:${JSON.stringify(keyed ?? null)}`;
+}
+/** Match a hook key (`"*"`, exact name, `"a|b"` pipe list, or `*` glob) to an action. */
+function hookMatches(pattern, action) {
+    if (pattern === "*")
+        return true;
+    if (pattern.includes("|"))
+        return pattern.split("|").some((p) => hookMatches(p.trim(), action));
+    if (pattern.includes("*")) {
+        const rx = new RegExp("^" + pattern.replace(/[.+^${}()[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$");
+        return rx.test(action);
+    }
+    return pattern === action;
+}
+export class Broker {
+    nodeID;
+    logger;
+    transporter;
+    requestTimeout;
+    defaultRetries;
+    cacher;
+    middlewares;
+    services = [];
+    /** action fullName → endpoint. */
+    actions = new Map();
+    started = false;
+    uid = 0;
+    constructor(options = {}) {
+        this.nodeID = options.nodeID ?? `node-${Math.random().toString(36).slice(2, 8)}`;
+        this.logger = options.logger ?? new Logger({ bindings: { nodeID: options.nodeID } });
+        this.transporter = options.transporter ?? new LocalTransporter();
+        this.requestTimeout = options.requestTimeout ?? 0;
+        this.defaultRetries = options.retries ?? 0;
+        this.cacher = options.cacher;
+        this.middlewares = options.middlewares ?? [];
+    }
+    /* ------------------------------ registration ---------------------------- */
+    /** Register a service from a schema (flattening any `mixins`). Returns the instance. */
+    createService(rawSchema) {
+        const schema = applyMixins(rawSchema);
+        schema.merged?.(schema);
+        const service = new Service(this, schema);
+        for (const [name, action] of service._actions) {
+            const full = `${service.fullName}.${name}`;
+            this.actions.set(full, { service, action });
+            // Internal caller: runs the full pipeline (hooks, timeout) but skips the
+            // visibility gate, so a service can reach its own `private` actions.
+            service.actions[name] = (params, opts = {}) => this.invoke(full, { service, action }, params, opts);
+        }
+        this.services.push(service);
+        void service._schema.created?.call(service);
+        this.logger.debug("service created", { service: service.fullName });
+        void this.broadcast("$services.changed", { service: service.fullName });
+        return service;
+    }
+    /** Look up a local service by (versioned) name. */
+    getLocalService(name) {
+        return this.services.find((s) => s.fullName === name || s.name === name);
+    }
+    /** Remove a service, running its `stopped` hook and unregistering its actions. */
+    async destroyService(service) {
+        for (const name of service._actions.keys()) {
+            this.actions.delete(`${service.fullName}.${name}`);
+        }
+        const idx = this.services.indexOf(service);
+        if (idx !== -1)
+            this.services.splice(idx, 1);
+        if (this.started)
+            await service._schema.stopped?.call(service);
+        void this.broadcast("$services.changed", { service: service.fullName });
+    }
+    /** Resolve once every named service is registered; polls until `timeout` (ms). */
+    async waitForServices(deps, timeout = 0, interval = 100) {
+        const names = toArray(deps).filter(Boolean);
+        const missing = () => names.filter((n) => !this.getLocalService(n));
+        let pending = missing();
+        if (!pending.length)
+            return;
+        const startedAt = Date.now();
+        while (pending.length) {
+            if (timeout && Date.now() - startedAt >= timeout) {
+                throw new Error(`waitForServices timed out after ${timeout}ms; still missing: ${pending.join(", ")}`);
+            }
+            await new Promise((r) => setTimeout(r, interval));
+            pending = missing();
+        }
+    }
+    /* ------------------------------- lifecycle ------------------------------ */
+    /** Connect the transporter and run every service's `started` hook. */
+    async start() {
+        if (this.started)
+            return;
+        await this.transporter.connect(this);
+        for (const service of this.services) {
+            if (service.dependencies.length) {
+                await this.waitForServices(service.dependencies, Number(service.settings.$dependencyTimeout) || 0);
+            }
+            await service._schema.started?.call(service);
+        }
+        this.started = true;
+        for (const mw of this.middlewares)
+            await mw.started?.(this);
+        this.logger.info("broker started", { nodeID: this.nodeID, services: this.services.length });
+        await this.broadcast("$broker.started");
+    }
+    /** Run every service's `stopped` hook (reverse order) and disconnect. */
+    async stop() {
+        if (!this.started)
+            return;
+        await this.broadcast("$broker.stopped");
+        for (const service of [...this.services].reverse()) {
+            await service._schema.stopped?.call(service);
+        }
+        for (const mw of [...this.middlewares].reverse())
+            await mw.stopped?.(this);
+        await this.transporter.disconnect();
+        this.started = false;
+        this.logger.info("broker stopped", { nodeID: this.nodeID });
+    }
+    /* --------------------------------- calls -------------------------------- */
+    /** A short unique id for tracing. */
+    generateUid() {
+        return `${this.nodeID}-${++this.uid}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    /** Invoke an action by name and resolve with its result. */
+    async call(action, params, opts = {}) {
+        const endpoint = this.actions.get(action);
+        // `private` actions are unreachable from `call` — hidden as if unregistered.
+        if (!endpoint || endpoint.action.visibility === "private")
+            throw new ServiceNotFoundError(action);
+        return this.invoke(action, endpoint, params, opts);
+    }
+    /* ------------------------------ introspection --------------------------- */
+    /** Whether a callable (non-private) action is registered. */
+    hasAction(name) {
+        const endpoint = this.actions.get(name);
+        return !!endpoint && endpoint.action.visibility !== "private";
+    }
+    /** The names of every callable (non-private) action, sorted. */
+    listActions() {
+        return [...this.actions.entries()]
+            .filter(([, e]) => e.action.visibility !== "private")
+            .map(([name]) => name)
+            .sort();
+    }
+    /** The full names of every registered service. */
+    listServices() {
+        return this.services.map((s) => s.fullName);
+    }
+    /** A registered service by full name or bare name. */
+    getService(name) {
+        return this.services.find((s) => s.fullName === name || s.name === name);
+    }
+    /** Invoke several actions at once — pass an array or a keyed map; returns the same shape. */
+    async mcall(defs, opts = {}) {
+        const { settled, ...callOpts } = opts;
+        const run = (d) => this.call(d.action, d.params, { ...callOpts, ...d.opts });
+        const collect = (p) => settled
+            ? p.then((value) => ({ status: "fulfilled", value }), (reason) => ({ status: "rejected", reason }))
+            : p;
+        if (Array.isArray(defs)) {
+            return Promise.all(defs.map((d) => collect(run(d))));
+        }
+        const entries = Object.entries(defs);
+        const keys = entries.map(([k]) => k);
+        const values = await Promise.all(entries.map(([, d]) => collect(run(d))));
+        return Object.fromEntries(keys.map((k, i) => [k, values[i]]));
+    }
+    /** The full call pipeline: build context → before hooks → handler → after hooks. */
+    async invoke(fullName, endpoint, params, opts) {
+        const { service, action } = endpoint;
+        const ctx = this.makeContext(service, fullName, params, opts);
+        const { before, after, error } = this.resolveHooks(service, action);
+        const timeout = opts.timeout ?? action.timeout ?? this.requestTimeout;
+        // Validate params against the action schema; the coerced value replaces them.
+        if (action.params) {
+            const result = action.params.safeParse(ctx.params);
+            if (!result.success) {
+                const errors = {};
+                for (const issue of result.error.issues) {
+                    const key = issue.path.map((p) => String(p)).join(".") || "_";
+                    (errors[key] ??= []).push(issue.message);
+                }
+                throw new ValidationException(errors);
+            }
+            ctx.params = result.data;
+        }
+        // Wrap the handler with `localAction` middlewares (first is outermost).
+        let handler = action.handler;
+        for (let i = this.middlewares.length - 1; i >= 0; i--) {
+            const wrap = this.middlewares[i].localAction;
+            if (wrap)
+                handler = wrap(handler, fullName);
+        }
+        const runOnce = () => {
+            const pipeline = (async () => {
+                for (const hook of before)
+                    await hook(ctx);
+                let res = await handler(ctx);
+                for (const hook of after)
+                    res = await hook(ctx, res);
+                return res;
+            })();
+            return timeout ? this.withTimeout(pipeline, timeout, fullName) : pipeline;
+        };
+        const execute = async () => {
+            // Retry the whole call on failure (total attempts = retries + 1).
+            const retries = opts.retries ?? this.defaultRetries;
+            let current;
+            for (let attempt = 0; attempt <= retries; attempt++) {
+                try {
+                    return await runOnce();
+                }
+                catch (err) {
+                    current = err;
+                }
+            }
+            // Every attempt failed: run error hooks, then fall back, else throw.
+            for (const hook of error) {
+                try {
+                    return await hook(ctx, current);
+                }
+                catch (e) {
+                    current = e;
+                }
+            }
+            if ("fallback" in opts && opts.fallback !== undefined) {
+                return typeof opts.fallback === "function"
+                    ? opts.fallback(current, ctx)
+                    : opts.fallback;
+            }
+            throw current;
+        };
+        // Cache the result when the action opts in and a cacher is configured.
+        if (action.cache && this.cacher) {
+            const cfg = typeof action.cache === "object" ? action.cache : {};
+            const key = cacheKey(fullName, ctx.params, cfg.keys);
+            return cfg.ttl != null
+                ? this.cacher.remember(key, cfg.ttl, execute)
+                : this.cacher.rememberForever(key, execute);
+        }
+        return execute();
+    }
+    /** Race a promise against a timeout, rejecting with `RequestTimeoutError`. */
+    withTimeout(p, timeout, action) {
+        let timer;
+        const guard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new RequestTimeoutError(action, timeout)), timeout);
+        });
+        return Promise.race([p, guard]).finally(() => clearTimeout(timer));
+    }
+    /**
+     * Assemble the hook chains for an action. Before: service wildcard → service
+     * named → action. After/Error run in reverse: action → service named →
+     * service wildcard.
+     */
+    resolveHooks(service, action) {
+        const gather = (map, wildcardFirst) => {
+            const wild = [];
+            const named = [];
+            for (const [pattern, fns] of Object.entries(map)) {
+                if (!hookMatches(pattern, action.name))
+                    continue;
+                (pattern.includes("*") ? wild : named).push(...fns);
+            }
+            return wildcardFirst ? [...wild, ...named] : [...named, ...wild];
+        };
+        return {
+            before: [...gather(service._hooks.before, true), ...action.hooks.before],
+            after: [...action.hooks.after, ...gather(service._hooks.after, false)],
+            error: [...action.hooks.error, ...gather(service._hooks.error, false)],
+        };
+    }
+    /* -------------------------------- events -------------------------------- */
+    /**
+     * Emit a *balanced* event: each listening service receives it once. In a
+     * multi-node cluster only one instance per service group is chosen; locally,
+     * with one instance per service, that's every listener.
+     */
+    emit(event, payload, opts = {}) {
+        return this.dispatch(event, payload, opts, false);
+    }
+    /** Broadcast an event to *every* listener (all instances, all groups). */
+    broadcast(event, payload, opts = {}) {
+        return this.dispatch(event, payload, opts, true);
+    }
+    /**
+     * Broadcast to every *local* listener only. On a single node this is identical
+     * to `broadcast`; the distinction matters once a real transporter would
+     * otherwise relay the event to remote nodes.
+     */
+    broadcastLocal(event, payload, opts = {}) {
+        return this.dispatch(event, payload, opts, true);
+    }
+    async dispatch(event, payload, opts, broadcast) {
+        // Locally there's a single instance per service, so balanced emit and
+        // broadcast reach the same handlers; the distinction matters once a real
+        // transporter registers remote instances.
+        const type = broadcast ? "broadcast" : "emit";
+        for (const service of this.services) {
+            for (const [pattern, listener] of service._events) {
+                if (!eventMatches(pattern, event))
+                    continue;
+                if (opts.groups && !opts.groups.includes(listener.group))
+                    continue;
+                const groups = opts.groups ?? [listener.group];
+                const ctx = this.makeContext(service, event, payload, { meta: opts.meta }, {
+                    name: event,
+                    type,
+                    groups,
+                });
+                await listener.handler(ctx);
+            }
+        }
+    }
+    /** True if any registered service listens for the given event. */
+    hasEventListener(event) {
+        return this.services.some((s) => [...s._events.keys()].some((pattern) => eventMatches(pattern, event)));
+    }
+    /* --------------------------------- misc --------------------------------- */
+    /**
+     * Measure round-trip latency (and clock difference) to a node. With the local
+     * transporter there's no network, so both are ~0 — the hook is here for real
+     * transporters to implement.
+     */
+    async ping(nodeID = this.nodeID) {
+        return { nodeID, elapsedTime: 0, timeDiff: 0 };
+    }
+    /** A snapshot of registered action names — handy for debugging. */
+    get registeredActions() {
+        return [...this.actions.keys()];
+    }
+    makeContext(service, name, params, opts, evt) {
+        const broker = this;
+        const parent = opts.parentCtx;
+        const meta = parent ? { ...parent.meta, ...opts.meta } : { ...(opts.meta ?? {}) };
+        const requestID = opts.requestID ?? parent?.requestID ?? broker.generateUid();
+        // The methods close over `ctx` so nested calls can chain from it (parentID,
+        // level, caller); they run only after the object exists, so the self-ref is safe.
+        const ctx = {
+            params,
+            meta,
+            locals: {},
+            headers: { ...(opts.headers ?? {}) },
+            broker,
+            service,
+            name,
+            action: evt ? undefined : { name },
+            event: evt,
+            eventName: evt?.name,
+            eventType: evt?.type,
+            eventGroups: evt?.groups,
+            nodeID: broker.nodeID,
+            id: broker.generateUid(),
+            parentID: parent?.id ?? null,
+            level: parent ? parent.level + 1 : 1,
+            caller: parent?.service?.fullName ?? null,
+            requestID,
+            call: (action, callParams, callOpts = {}) => broker.call(action, callParams, { ...callOpts, parentCtx: ctx }),
+            mcall: (defs, callOpts = {}) => broker.mcall(defs, { ...callOpts, parentCtx: ctx }),
+            toJSON: () => ({
+                id: ctx.id,
+                requestID: ctx.requestID,
+                parentID: ctx.parentID,
+                level: ctx.level,
+                nodeID: ctx.nodeID,
+                caller: ctx.caller,
+                name: ctx.name,
+                eventType: ctx.eventType,
+                meta: ctx.meta,
+            }),
+            emit: (ev, evPayload, evOpts = {}) => broker.emit(ev, evPayload, { ...evOpts, meta: { ...ctx.meta, ...evOpts.meta } }),
+            broadcast: (ev, evPayload, evOpts = {}) => broker.broadcast(ev, evPayload, { ...evOpts, meta: { ...ctx.meta, ...evOpts.meta } }),
+        };
+        return ctx;
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let instance = new Broker();
+/** Register the default broker returned by `broker()`. */
+export function setBroker(next) {
+    instance = next;
+    return instance;
+}
+/** The default broker instance. */
+export function broker() {
+    return instance;
+}

package/dist/core/crypto.d.ts

@@ -7,11 +7,14 @@
  *
  *   const token = await encryption.encrypt({ userId: 1 });
  *   await encryption.decrypt(token);             // { userId: 1 } | null
+ *
+ *   const token = await jwt.sign({ sub: "42" }, { expiresIn: "1h" });
+ *   await jwt.verify(token);                      // { sub: "42", iat, exp } | null
  */
 export declare const hash: {
     /** Hash a password (PBKDF2-SHA256 with a random salt). */
     make(password: string, iterations?: number): Promise<string>;
-    /** Verify a password against a stored hash. */
+    /** Verify a password against a stored hash. Returns false for any malformed hash. */
     verify(hashed: string, password: string): Promise<boolean>;
     /** Whether a hash was made with fewer iterations than the current default. */
     needsRehash(hashed: string, iterations?: number): boolean;
@@ -22,3 +25,50 @@ export declare const encryption: {
     /** Decrypt a value; returns null if the payload is tampered or invalid. */
     decrypt<T = unknown>(payload: string): Promise<T | null>;
 };
+/** Standard registered claims, plus whatever custom fields you sign. */
+export interface JwtPayload {
+    /** Subject — conventionally the user id. */
+    sub?: string;
+    /** Issued-at (seconds since the epoch); set automatically by `sign`. */
+    iat?: number;
+    /** Expiry (seconds since the epoch); set from `expiresIn`. */
+    exp?: number;
+    /** Not-before (seconds since the epoch); the token is invalid until then. */
+    nbf?: number;
+    /** Issuer. */
+    iss?: string;
+    /** Audience. */
+    aud?: string;
+    [claim: string]: unknown;
+}
+export interface JwtSignOptions {
+    /** Lifetime — seconds (number) or a duration string like `"30s"`, `"15m"`, `"1h"`, `"7d"`. */
+    expiresIn?: number | string;
+    /** Sets the `iss` claim. */
+    issuer?: string;
+    /** Sets the `aud` claim. */
+    audience?: string;
+    /** Sets the `sub` claim (overrides any `sub` already in the payload). */
+    subject?: string;
+    /** Signing secret; defaults to `config('app.key')`. */
+    secret?: string;
+}
+export interface JwtVerifyOptions {
+    /** Require this `iss`; a token that doesn't match is rejected. */
+    issuer?: string;
+    /** Require this `aud`; a token that doesn't match is rejected. */
+    audience?: string;
+    /** Verifying secret; defaults to `config('app.key')`. */
+    secret?: string;
+}
+export declare const jwt: {
+    /** Sign a payload into an HS256 JWT. Adds `iat`, and `exp` when `expiresIn` is set. */
+    sign(payload: JwtPayload, options?: JwtSignOptions): Promise<string>;
+    /**
+     * Verify an HS256 JWT and return its payload, or `null` if the token is
+     * malformed, tampered, expired, not-yet-valid, or fails an issuer/audience
+     * check. Only HS256 is accepted — `alg: none` and asymmetric algs are refused,
+     * closing the classic JWT algorithm-confusion hole.
+     */
+    verify<T extends JwtPayload = JwtPayload>(token: string, options?: JwtVerifyOptions): Promise<T | null>;
+};