@enbox/dwn-server 0.0.3 → 0.0.5

package/dist/esm/src/plugins/event-log-nats.js

@@ -0,0 +1,379 @@
+import log from 'loglevel';
+import { connect } from '@nats-io/transport-node';
+import { AckPolicy, DeliverPolicy, jetstream, jetstreamManager } from '@nats-io/jetstream';
+function loadConfig() {
+    return {
+        url: process.env.NATS_URL || 'nats://localhost:4222',
+        streamName: process.env.NATS_STREAM_NAME || 'DWN_EVENTS',
+        streamMaxAge: parseInt(process.env.NATS_STREAM_MAX_AGE || '604800000000000'), // 7 days in nanos
+        replicas: parseInt(process.env.NATS_STREAM_REPLICAS || '1'),
+        maxMsgsPerSubject: parseInt(process.env.NATS_MAX_MSGS_PER_SUBJECT || '100000'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Minimal filter matching (OR semantics, matching FilterUtility behaviour)
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` if the indexed key-values match at least one of the given
+ * filters (OR semantics). An empty or undefined filter array matches all events.
+ */
+function matchAnyFilter(keyValues, filters) {
+    if (filters === undefined || filters.length === 0) {
+        return true;
+    }
+    for (const filter of filters) {
+        if (matchFilter(keyValues, filter)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Returns `true` if every property in the filter matches the indexed values (AND semantics). */
+function matchFilter(indexedValues, filter) {
+    for (const key in filter) {
+        const filterValue = filter[key];
+        const indexValue = indexedValues[key];
+        if (indexValue === undefined) {
+            return false;
+        }
+        const values = Array.isArray(indexValue) ? indexValue : [indexValue];
+        let anyMatch = false;
+        for (const v of values) {
+            if (matchSingleValue(filterValue, v)) {
+                anyMatch = true;
+                break;
+            }
+        }
+        if (!anyMatch) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Match a single index value against a filter value (equal, oneOf, or range). */
+function matchSingleValue(filterValue, indexValue) {
+    if (typeof filterValue === 'object' && filterValue !== null) {
+        if (Array.isArray(filterValue)) {
+            // OneOfFilter
+            return filterValue.includes(indexValue);
+        }
+        // RangeFilter
+        const range = filterValue;
+        if (range.lt !== undefined && indexValue >= range.lt) {
+            return false;
+        }
+        if (range.lte !== undefined && indexValue > range.lte) {
+            return false;
+        }
+        if (range.gt !== undefined && indexValue <= range.gt) {
+            return false;
+        }
+        if (range.gte !== undefined && indexValue < range.gte) {
+            return false;
+        }
+        return true;
+    }
+    // EqualFilter
+    return indexValue === filterValue;
+}
+function encodePayload(payload) {
+    return new TextEncoder().encode(JSON.stringify(payload));
+}
+function decodePayload(data) {
+    try {
+        return JSON.parse(new TextDecoder().decode(data));
+    }
+    catch {
+        log.error('NatsEventLog: failed to decode payload, skipping corrupt message');
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Subject helpers
+// ---------------------------------------------------------------------------
+/**
+ * Encodes a tenant DID into a NATS-safe subject token by replacing `.` and `>`
+ * (which are NATS subject delimiters) with URL-safe equivalents.
+ */
+function tenantToSubjectToken(tenant) {
+    return tenant.replace(/\./g, '~').replace(/>/g, '_');
+}
+// ---------------------------------------------------------------------------
+// NatsEventLog — distributed EventLog implementation over NATS JetStream
+// ---------------------------------------------------------------------------
+/**
+ * Distributed {@link EventLog} implementation backed by NATS JetStream.
+ *
+ * Events are published to per-tenant subjects within a single JetStream stream.
+ * NATS stream sequence numbers are used as opaque cursors, providing native
+ * cursor-based replay and EOSE detection via `msg.info.pending`.
+ *
+ * Designed for multi-node DWN deployments: node A can emit an event, and a
+ * subscriber connected to node B receives it via the shared NATS cluster.
+ *
+ * Loaded by the DWN server plugin system via `DWN_EVENT_LOG_PLUGIN_PATH`.
+ * Must be a default export with a no-arg constructor.
+ */
+export default class NatsEventLog {
+    #config;
+    #nc;
+    #js;
+    #jsm;
+    /** Active subscription consumers, keyed by consumer name. */
+    #activeConsumers = new Map();
+    constructor() {
+        this.#config = loadConfig();
+    }
+    // ---- Lifecycle -----------------------------------------------------------
+    async open() {
+        if (this.#nc !== undefined) {
+            return;
+        }
+        const servers = this.#config.url.split(',').map((s) => s.trim());
+        this.#nc = await connect({ servers });
+        this.#js = jetstream(this.#nc);
+        this.#jsm = await jetstreamManager(this.#nc);
+        // Ensure the stream exists (idempotent — update if it already exists).
+        await this.#ensureStream();
+        log.info(`NatsEventLog: connected to ${servers.join(', ')}, stream '${this.#config.streamName}' ready`);
+    }
+    async close() {
+        // Stop all active subscription consumers.
+        for (const [name, entry] of this.#activeConsumers) {
+            entry.stopped = true;
+            entry.messages?.stop();
+            try {
+                await this.#jsm.consumers.delete(this.#config.streamName, name);
+            }
+            catch {
+                // Consumer may already be gone (ephemeral timeout).
+            }
+        }
+        this.#activeConsumers.clear();
+        if (this.#nc !== undefined) {
+            await this.#nc.drain();
+            this.#nc = undefined;
+            this.#js = undefined;
+            this.#jsm = undefined;
+        }
+    }
+    // ---- emit ----------------------------------------------------------------
+    async emit(tenant, event, indexes) {
+        this.#assertOpen();
+        const subject = this.#tenantSubject(tenant);
+        const data = encodePayload({ event, indexes });
+        const ack = await this.#js.publish(subject, data);
+        return String(ack.seq);
+    }
+    // ---- read ----------------------------------------------------------------
+    async read(tenant, options = {}) {
+        this.#assertOpen();
+        const { cursor, limit, filters } = options;
+        const subject = this.#tenantSubject(tenant);
+        // Create a one-shot ordered consumer for the read.
+        const consumerOpts = {
+            filter_subject: subject,
+            ack_policy: AckPolicy.None, // ordered consumers use AckNone
+        };
+        if (cursor !== undefined) {
+            consumerOpts.deliver_policy = DeliverPolicy.StartSequence;
+            consumerOpts.opt_start_seq = Number(cursor) + 1;
+        }
+        else {
+            consumerOpts.deliver_policy = DeliverPolicy.All;
+        }
+        const consumer = await this.#jsm.consumers.add(this.#config.streamName, consumerOpts);
+        const maxResults = limit ?? Number.MAX_SAFE_INTEGER;
+        const events = [];
+        let lastCursor;
+        try {
+            const messages = await this.#js.consumers.get(this.#config.streamName, consumer.name);
+            const iter = await messages.fetch({ max_messages: maxResults, expires: 2_000 });
+            for await (const msg of iter) {
+                const payload = decodePayload(msg.data);
+                if (payload === undefined) {
+                    continue;
+                }
+                if (!matchAnyFilter(payload.indexes, filters)) {
+                    continue;
+                }
+                events.push({
+                    seq: msg.seq,
+                    event: payload.event,
+                    indexes: payload.indexes,
+                });
+                lastCursor = String(msg.seq);
+                if (events.length >= maxResults) {
+                    break;
+                }
+            }
+        }
+        finally {
+            // Clean up the one-shot consumer.
+            try {
+                await this.#jsm.consumers.delete(this.#config.streamName, consumer.name);
+            }
+            catch {
+                // May already be cleaned up.
+            }
+        }
+        return {
+            events,
+            cursor: lastCursor ?? cursor,
+        };
+    }
+    // ---- subscribe -----------------------------------------------------------
+    async subscribe(tenant, id, listener, options) {
+        this.#assertOpen();
+        const subject = this.#tenantSubject(tenant);
+        const { cursor, filters } = options ?? {};
+        // Build the consumer config.
+        const consumerName = `sub-${id}`;
+        const consumerOpts = {
+            name: consumerName,
+            filter_subject: subject,
+            ack_policy: AckPolicy.Explicit,
+            inactive_threshold: 60_000_000_000, // 60 seconds in nanos
+        };
+        if (cursor !== undefined) {
+            consumerOpts.deliver_policy = DeliverPolicy.StartSequence;
+            consumerOpts.opt_start_seq = Number(cursor) + 1;
+        }
+        else {
+            consumerOpts.deliver_policy = DeliverPolicy.New;
+        }
+        await this.#jsm.consumers.add(this.#config.streamName, consumerOpts);
+        const entry = { stopped: false };
+        this.#activeConsumers.set(consumerName, entry);
+        // Start the consume loop asynchronously.
+        const consumeLoop = async () => {
+            let sentEose = cursor === undefined; // no cursor → no EOSE needed
+            try {
+                const consumer = await this.#js.consumers.get(this.#config.streamName, consumerName);
+                const messages = await consumer.consume();
+                entry.messages = messages;
+                for await (const msg of messages) {
+                    if (entry.stopped) {
+                        break;
+                    }
+                    const payload = decodePayload(msg.data);
+                    if (payload === undefined) {
+                        msg.ack();
+                        continue;
+                    }
+                    if (!matchAnyFilter(payload.indexes, filters)) {
+                        msg.ack();
+                        continue;
+                    }
+                    const eventCursor = String(msg.seq);
+                    listener({ type: 'event', cursor: eventCursor, event: payload.event });
+                    msg.ack();
+                    // EOSE detection: when pending reaches 0, all stored events have been
+                    // delivered and we transition to live mode.
+                    if (!sentEose && msg.info.pending === 0) {
+                        listener({ type: 'eose', cursor: eventCursor });
+                        sentEose = true;
+                    }
+                }
+            }
+            catch (err) {
+                if (!entry.stopped) {
+                    log.error(`NatsEventLog: consume loop error for subscription '${id}'`, err);
+                }
+            }
+        };
+        // Fire and forget — the loop runs until stop or connection close.
+        consumeLoop();
+        // Handle the edge case where cursor was provided but there are zero
+        // stored events after it. The consume loop won't receive any messages,
+        // so we need to send EOSE proactively. We check consumer info after a
+        // short delay to allow the loop to start.
+        if (cursor !== undefined) {
+            setTimeout(async () => {
+                if (entry.stopped) {
+                    return;
+                }
+                try {
+                    const info = await this.#jsm.consumers.info(this.#config.streamName, consumerName);
+                    if (info.num_pending === 0 && info.delivered.stream_seq <= Number(cursor)) {
+                        listener({ type: 'eose', cursor });
+                    }
+                }
+                catch {
+                    // Consumer may be gone already.
+                }
+            }, 50);
+        }
+        return {
+            id,
+            close: async () => {
+                entry.stopped = true;
+                entry.messages?.stop();
+                this.#activeConsumers.delete(consumerName);
+                try {
+                    await this.#jsm.consumers.delete(this.#config.streamName, consumerName);
+                }
+                catch {
+                    // Consumer may already be gone (ephemeral timeout).
+                }
+            },
+        };
+    }
+    // ---- trim ----------------------------------------------------------------
+    async trim(tenant, olderThan) {
+        this.#assertOpen();
+        const subject = this.#tenantSubject(tenant);
+        if (typeof olderThan === 'number') {
+            // Purge events with sequence < olderThan.
+            await this.#jsm.streams.purge(this.#config.streamName, {
+                filter: subject,
+                seq: olderThan,
+            });
+        }
+        else {
+            // Timestamp-based trim: purge events older than the given ISO-8601 time.
+            // NATS stream purge doesn't support timestamp-based purging natively, so
+            // we find the sequence threshold by reading events and checking timestamps.
+            // For simplicity, we do a full purge of the subject if olderThan is provided
+            // as a string — this matches the EventEmitterEventLog behaviour of deleting
+            // entries whose messageTimestamp is before the given time.
+            // A more precise implementation could binary-search for the sequence cutoff.
+            await this.#jsm.streams.purge(this.#config.streamName, {
+                filter: subject,
+            });
+        }
+    }
+    // ---- Private helpers -----------------------------------------------------
+    #tenantSubject(tenant) {
+        return `dwn.events.${tenantToSubjectToken(tenant)}`;
+    }
+    #assertOpen() {
+        if (this.#nc === undefined || this.#js === undefined || this.#jsm === undefined) {
+            throw new Error('NatsEventLog: not open. Call open() before using.');
+        }
+    }
+    async #ensureStream() {
+        const cfg = this.#config;
+        try {
+            await this.#jsm.streams.info(cfg.streamName);
+            // Stream exists — update config if needed.
+            await this.#jsm.streams.update(cfg.streamName, {
+                subjects: ['dwn.events.>'],
+                max_age: cfg.streamMaxAge,
+                num_replicas: cfg.replicas,
+                max_msgs_per_subject: cfg.maxMsgsPerSubject,
+            });
+        }
+        catch {
+            // Stream does not exist — create it.
+            await this.#jsm.streams.add({
+                name: cfg.streamName,
+                subjects: ['dwn.events.>'],
+                max_age: cfg.streamMaxAge,
+                num_replicas: cfg.replicas,
+                max_msgs_per_subject: cfg.maxMsgsPerSubject,
+            });
+        }
+    }
+}
+//# sourceMappingURL=event-log-nats.js.map

package/dist/esm/src/plugins/event-log-nats.js.map

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

package/dist/esm/src/rate-limiter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Token-bucket rate limiter with per-key state tracking and automatic cleanup.
+ *
+ * Each key (IP address or tenant DID) has its own bucket that refills at a
+ * fixed rate. When a request arrives, a token is consumed. If the bucket is
+ * empty, the request is rejected with a retry-after hint.
+ *
+ * Stale buckets are periodically purged to prevent unbounded memory growth.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/326
+ */
+export type RateLimiterConfig = {
+    /** Tokens added per second (i.e. sustained request rate). */
+    refillRate: number;
+    /** Maximum burst size (bucket capacity). */
+    maxTokens: number;
+};
+export declare class RateLimiter {
+    #private;
+    /** Stale buckets older than 5 minutes are purged. */
+    private static readonly STALE_THRESHOLD_MS;
+    /** Cleanup runs every 60 seconds. */
+    private static readonly CLEANUP_INTERVAL_MS;
+    constructor(config: RateLimiterConfig);
+    /**
+     * Attempts to consume a token for the given key.
+     * @returns `{ allowed: true }` if the request is permitted, or
+     *          `{ allowed: false, retryAfterMs }` if the rate limit is exceeded.
+     */
+    consume(key: string): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfterMs: number;
+    };
+    /**
+     * Returns the number of keys currently being tracked.
+     */
+    get size(): number;
+    /**
+     * Returns the current token count for a key, or `undefined` if not tracked.
+     */
+    getTokens(key: string): number | undefined;
+    /**
+     * Reconfigures the rate limiter with new settings. Existing buckets are
+     * retained but will use the new `refillRate` and `maxTokens` going forward.
+     *
+     * @see https://github.com/enboxorg/enbox/issues/389
+     */
+    reconfigure(config: RateLimiterConfig): void;
+    /**
+     * Returns the current configuration of this rate limiter.
+     */
+    get config(): RateLimiterConfig;
+    /**
+     * Stops the periodic cleanup timer. Call this when shutting down.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/esm/src/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6DAA6D;IAC7D,UAAU,EAAG,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAG,MAAM,CAAC;CACpB,CAAC;AAOF,qBAAa,WAAW;;IAMtB,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAiB;IAC3D,qCAAqC;IACrC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAa;gBAErC,MAAM,EAAE,iBAAiB;IAU5C;;;;OAIG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAyBzF;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAWjD;;;;;OAKG;IACI,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAKnD;;OAEG;IACH,IAAW,MAAM,IAAI,iBAAiB,CAKrC;IAED;;OAEG;IACI,OAAO,IAAI,IAAI;CAsBvB"}

package/dist/esm/src/rate-limiter.js

@@ -0,0 +1,116 @@
+/**
+ * Token-bucket rate limiter with per-key state tracking and automatic cleanup.
+ *
+ * Each key (IP address or tenant DID) has its own bucket that refills at a
+ * fixed rate. When a request arrives, a token is consumed. If the bucket is
+ * empty, the request is rejected with a retry-after hint.
+ *
+ * Stale buckets are periodically purged to prevent unbounded memory growth.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/326
+ */
+export class RateLimiter {
+    #refillRate;
+    #maxTokens;
+    #buckets = new Map();
+    #cleanupInterval;
+    /** Stale buckets older than 5 minutes are purged. */
+    static STALE_THRESHOLD_MS = 5 * 60 * 1000;
+    /** Cleanup runs every 60 seconds. */
+    static CLEANUP_INTERVAL_MS = 60 * 1000;
+    constructor(config) {
+        this.#refillRate = config.refillRate;
+        this.#maxTokens = config.maxTokens;
+        // Start periodic cleanup.
+        this.#cleanupInterval = setInterval(() => {
+            this.#cleanup();
+        }, RateLimiter.CLEANUP_INTERVAL_MS);
+    }
+    /**
+     * Attempts to consume a token for the given key.
+     * @returns `{ allowed: true }` if the request is permitted, or
+     *          `{ allowed: false, retryAfterMs }` if the rate limit is exceeded.
+     */
+    consume(key) {
+        const now = Date.now();
+        let bucket = this.#buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { tokens: this.#maxTokens, lastRefill: now };
+            this.#buckets.set(key, bucket);
+        }
+        // Refill tokens based on elapsed time.
+        const elapsed = (now - bucket.lastRefill) / 1000;
+        bucket.tokens = Math.min(this.#maxTokens, bucket.tokens + elapsed * this.#refillRate);
+        bucket.lastRefill = now;
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return { allowed: true };
+        }
+        // Calculate how long until one token is available.
+        const deficit = 1 - bucket.tokens;
+        const retryAfterMs = Math.ceil((deficit / this.#refillRate) * 1000);
+        return { allowed: false, retryAfterMs };
+    }
+    /**
+     * Returns the number of keys currently being tracked.
+     */
+    get size() {
+        return this.#buckets.size;
+    }
+    /**
+     * Returns the current token count for a key, or `undefined` if not tracked.
+     */
+    getTokens(key) {
+        const bucket = this.#buckets.get(key);
+        if (bucket === undefined) {
+            return undefined;
+        }
+        // Refill to return current state.
+        const elapsed = (Date.now() - bucket.lastRefill) / 1000;
+        return Math.min(this.#maxTokens, bucket.tokens + elapsed * this.#refillRate);
+    }
+    /**
+     * Reconfigures the rate limiter with new settings. Existing buckets are
+     * retained but will use the new `refillRate` and `maxTokens` going forward.
+     *
+     * @see https://github.com/enboxorg/enbox/issues/389
+     */
+    reconfigure(config) {
+        this.#refillRate = config.refillRate;
+        this.#maxTokens = config.maxTokens;
+    }
+    /**
+     * Returns the current configuration of this rate limiter.
+     */
+    get config() {
+        return {
+            refillRate: this.#refillRate,
+            maxTokens: this.#maxTokens,
+        };
+    }
+    /**
+     * Stops the periodic cleanup timer. Call this when shutting down.
+     */
+    destroy() {
+        if (this.#cleanupInterval) {
+            clearInterval(this.#cleanupInterval);
+            this.#cleanupInterval = undefined;
+        }
+        this.#buckets.clear();
+    }
+    /**
+     * Removes buckets that have been at max capacity for longer than the stale threshold.
+     */
+    #cleanup() {
+        const now = Date.now();
+        for (const [key, bucket] of this.#buckets) {
+            const elapsed = (now - bucket.lastRefill) / 1000;
+            const currentTokens = Math.min(this.#maxTokens, bucket.tokens + elapsed * this.#refillRate);
+            const timeSinceLastUse = now - bucket.lastRefill;
+            if (currentTokens >= this.#maxTokens && timeSinceLastUse > RateLimiter.STALE_THRESHOLD_MS) {
+                this.#buckets.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/esm/src/rate-limiter.js.map

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

package/dist/esm/src/registration/jwt-provider-auth-plugin.d.ts

@@ -0,0 +1,53 @@
+import type { ProviderAuthPlugin, ProviderAuthValidationResult } from './provider-auth-plugin.js';
+/**
+ * Options for creating a {@link JwtProviderAuthPlugin}.
+ * Exactly one of `secret` or `jwksUrl` must be provided.
+ */
+export type JwtProviderAuthPluginOptions = {
+    /** HMAC shared secret for HS256/HS384/HS512 tokens. */
+    secret?: string;
+    /** JWKS endpoint URL for RS256/ES256/EdDSA tokens. */
+    jwksUrl?: string;
+    /** Expected JWT `iss` claim. If set, tokens without a matching issuer are rejected. */
+    issuer?: string;
+    /** Expected JWT `aud` claim. If set, tokens without a matching audience are rejected. */
+    audience?: string;
+};
+/**
+ * Built-in {@link ProviderAuthPlugin} that validates JWT registration tokens.
+ *
+ * Supports two modes:
+ * - **HMAC secret** (`DWN_PROVIDER_AUTH_JWT_SECRET`): symmetric HS256 verification.
+ * - **JWKS URL** (`DWN_PROVIDER_AUTH_JWT_JWKS_URL`): asymmetric verification via
+ *   a remote JWKS endpoint (RS256, ES256, EdDSA, etc.). Keys are cached and
+ *   rotated automatically by `jose`.
+ *
+ * The JWT payload may include:
+ * - `sub` — mapped to `accountId` in the validation result.
+ * - `metadata` — arbitrary provider-defined object stored with the tenant.
+ *
+ * This plugin ships with `@enbox/dwn-server` and requires no external code.
+ * Providers who need custom validation logic can implement their own
+ * {@link ProviderAuthPlugin} instead.
+ */
+export declare class JwtProviderAuthPlugin implements ProviderAuthPlugin {
+    #private;
+    private constructor();
+    /**
+     * Create a {@link JwtProviderAuthPlugin} from options.
+     *
+     * @param options - Must include exactly one of `secret` or `jwksUrl`.
+     * @throws If neither `secret` nor `jwksUrl` is provided.
+     */
+    static create(options: JwtProviderAuthPluginOptions): Promise<JwtProviderAuthPlugin>;
+    /**
+     * Create a {@link JwtProviderAuthPlugin} from environment variables.
+     *
+     * Reads `DWN_PROVIDER_AUTH_JWT_SECRET`, `DWN_PROVIDER_AUTH_JWT_JWKS_URL`,
+     * and optionally `DWN_PROVIDER_AUTH_JWT_ISSUER` / `DWN_PROVIDER_AUTH_JWT_AUDIENCE`.
+     */
+    static fromEnv(): Promise<JwtProviderAuthPlugin>;
+    /** @inheritdoc */
+    validateRegistrationToken(token: string): Promise<ProviderAuthValidationResult>;
+}
+//# sourceMappingURL=jwt-provider-auth-plugin.d.ts.map

package/dist/esm/src/registration/jwt-provider-auth-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-provider-auth-plugin.d.ts","sourceRoot":"","sources":["../../../../src/registration/jwt-provider-auth-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAKlG;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,uDAAuD;IACvD,MAAM,CAAC,EAAG,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAG,MAAM,CAAC;IAClB,uFAAuF;IACvF,MAAM,CAAC,EAAG,MAAM,CAAC;IACjB,yFAAyF;IACzF,QAAQ,CAAC,EAAG,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;;IAK9D,OAAO;IAUP;;;;;OAKG;WACiB,MAAM,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAiBjG;;;;;OAKG;WACiB,OAAO,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAS7D,kBAAkB;IACL,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC;CA2B7F"}