@grantex/sdk 0.6.0 → 0.7.0

package/dist/revocations/feed.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The revocation feed client (PRD G-6).
+ *
+ * It takes a snapshot of everything currently revoked, then follows the live
+ * stream, so `enforce()` can deny a call on a grant that was revoked seconds
+ * ago without a network round trip per call.
+ *
+ * The important part is what happens when it cannot keep up. The feed records
+ * when it last heard from the auth service; if that is longer ago than
+ * `staleAfterMs`, it reports itself stale and `enforce()` denies rather than
+ * allowing calls on information it knows may be out of date.
+ */
+import type { HttpClient } from '../http.js';
+import { type CredentialRef, type RevocationMatch } from './set.js';
+export interface RevocationFeedOptions {
+    /**
+     * How long the feed may go without hearing from the auth service before it
+     * is stale and calls fail closed. Default 5000 ms.
+     */
+    staleAfterMs?: number;
+    /** Delay before reconnecting a dropped stream. Default 500 ms. */
+    reconnectDelayMs?: number;
+    /** `stream` (Server-Sent Events) or `poll` (long polling). Default `stream`, falling back to `poll`. */
+    transport?: 'stream' | 'poll';
+}
+export type FeedUnavailableReason = 'disabled' | 'not_ready' | 'unauthorized' | 'network';
+export interface RevocationFeedState {
+    /** A snapshot has been read at least once. */
+    synced: boolean;
+    /**
+     * When the feed last heard from the auth service, on a monotonic clock
+     * (0 if never). Comparable with `performance.now()`, not with `Date.now()`.
+     */
+    freshAt: number;
+    /** Feed position of the last entry applied. */
+    cursor: number;
+    /** Identifiers currently known to be revoked or suspended. */
+    known: number;
+    /** Why the feed is not usable, if it is not. */
+    unavailable: FeedUnavailableReason | null;
+}
+export declare class RevocationFeed {
+    #private;
+    constructor(http: HttpClient, options?: RevocationFeedOptions);
+    get staleAfterMs(): number;
+    state(): RevocationFeedState;
+    /** Synced recently enough to be trusted. */
+    isFresh(now?: number): boolean;
+    /** Why this credential must not be used, according to what the feed knows. */
+    match(ref: CredentialRef, now?: number): RevocationMatch | null;
+    /** Start following the feed. Idempotent. */
+    start(): void;
+    /** Stop following, and forget what was known (a restarted feed re-reads the snapshot). */
+    stop(): Promise<void>;
+    /**
+     * Wait until the feed is fresh, or the timeout passes. Returns whether it is
+     * fresh: `false` means callers must fail closed.
+     */
+    ready(timeoutMs?: number): Promise<boolean>;
+}
+//# sourceMappingURL=feed.d.ts.map

package/dist/revocations/feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.d.ts","sourceRoot":"","sources":["../../src/revocations/feed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAc,KAAK,aAAa,EAAwB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAEtG,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C;AAqBD,qBAAa,cAAc;;IAkBzB,YAAY,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B,EAKhE;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,IAAI,mBAAmB,CAQ3B;IAED,4CAA4C;IAC5C,OAAO,CAAC,GAAG,GAAE,MAAuB,GAAG,OAAO,CAE7C;IAED,8EAA8E;IAC9E,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe,GAAG,IAAI,CAE1E;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,CAKZ;IAED,0FAA0F;IACpF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAa1B;IAED;;;OAGG;IACG,KAAK,CAAC,SAAS,GAAE,MAA2B,GAAG,OAAO,CAAC,OAAO,CAAC,CAepE;CAqJF"}

package/dist/revocations/feed.js

@@ -0,0 +1,282 @@
+import { RevokedSet } from './set.js';
+/**
+ * Freshness is measured on a monotonic clock: a wall-clock jump backwards
+ * must not make a stale feed look current.
+ */
+const monotonicNow = () => (typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance.now() : Date.now());
+const DEFAULT_STALE_AFTER_MS = 5_000;
+const DEFAULT_RECONNECT_DELAY_MS = 500;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+const PRUNE_INTERVAL_MS = 60_000;
+export class RevocationFeed {
+    #http;
+    #set = new RevokedSet();
+    #staleAfterMs;
+    #reconnectDelayMs;
+    #transport;
+    #running = false;
+    #synced = false;
+    #freshAt = 0;
+    #cursor = 0;
+    #unavailable = null;
+    #controller = null;
+    #loop = null;
+    #reader = null;
+    #prunedAt = 0;
+    #waiters = [];
+    constructor(http, options = {}) {
+        this.#http = http;
+        this.#staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+        this.#reconnectDelayMs = options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS;
+        this.#transport = options.transport ?? 'stream';
+    }
+    get staleAfterMs() {
+        return this.#staleAfterMs;
+    }
+    state() {
+        return {
+            synced: this.#synced,
+            freshAt: this.#freshAt,
+            cursor: this.#cursor,
+            known: this.#set.size,
+            unavailable: this.#unavailable,
+        };
+    }
+    /** Synced recently enough to be trusted. */
+    isFresh(now = monotonicNow()) {
+        return this.#synced && this.#unavailable === null && now - this.#freshAt <= this.#staleAfterMs;
+    }
+    /** Why this credential must not be used, according to what the feed knows. */
+    match(ref, now = Date.now()) {
+        return this.#set.match(ref, now);
+    }
+    /** Start following the feed. Idempotent. */
+    start() {
+        if (this.#running)
+            return;
+        this.#running = true;
+        this.#controller = new AbortController();
+        this.#loop = this.#run().catch(() => { });
+    }
+    /** Stop following, and forget what was known (a restarted feed re-reads the snapshot). */
+    async stop() {
+        this.#running = false;
+        this.#controller?.abort();
+        // An open stream is not interrupted by aborting a fetch that already
+        // resolved, so release the reader too.
+        await this.#reader?.cancel().catch(() => { });
+        const loop = this.#loop;
+        this.#loop = null;
+        this.#synced = false;
+        this.#freshAt = 0;
+        this.#set.clear();
+        this.#wake();
+        if (loop)
+            await loop;
+    }
+    /**
+     * Wait until the feed is fresh, or the timeout passes. Returns whether it is
+     * fresh: `false` means callers must fail closed.
+     */
+    async ready(timeoutMs = this.#staleAfterMs) {
+        this.start();
+        const deadline = monotonicNow() + timeoutMs;
+        for (;;) {
+            if (this.isFresh())
+                return true;
+            if (this.#unavailable !== null || monotonicNow() >= deadline)
+                return this.isFresh();
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, Math.min(50, Math.max(1, deadline - monotonicNow())));
+                timer.unref?.();
+                this.#waiters.push(() => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+        }
+    }
+    #wake() {
+        const waiters = this.#waiters;
+        this.#waiters = [];
+        for (const waiter of waiters)
+            waiter();
+    }
+    #touch() {
+        this.#freshAt = monotonicNow();
+        // Entries whose credential has expired can no longer be used; dropping
+        // them here bounds the set without a timer of its own.
+        if (this.#freshAt - this.#prunedAt > PRUNE_INTERVAL_MS) {
+            this.#set.prune();
+            this.#prunedAt = this.#freshAt;
+        }
+        this.#unavailable = null;
+        this.#wake();
+    }
+    async #run() {
+        let delay = this.#reconnectDelayMs;
+        while (this.#running) {
+            try {
+                await this.#snapshot();
+                delay = this.#reconnectDelayMs;
+                if (this.#transport === 'stream') {
+                    const streamed = await this.#stream();
+                    if (!streamed)
+                        await this.#poll();
+                    // A stream that ended cleanly (a server restart, a proxy timeout)
+                    // must not be reconnected in a tight loop.
+                    else if (this.#running)
+                        await sleep(this.#reconnectDelayMs, this.#controller?.signal);
+                }
+                else {
+                    await this.#poll();
+                }
+            }
+            catch (err) {
+                this.#unavailable = classify(err);
+                this.#synced = false;
+                this.#wake();
+                await sleep(delay, this.#controller?.signal);
+                delay = Math.min(delay * 2, MAX_RECONNECT_DELAY_MS);
+            }
+        }
+    }
+    async #snapshot() {
+        let pageToken;
+        let cursor = 0;
+        // Collected first and swapped in once every page has arrived. A snapshot
+        // is the whole truth about what is revoked *now*, so applying it on top
+        // of what the set already held kept anything resumed while this client
+        // was disconnected — denied until it expired. Swapping only after the
+        // last page means a failure part way through leaves the previous set
+        // intact rather than a half-built one.
+        const entries = [];
+        do {
+            // `pageToken` is empty only on the first pass; the loop condition ends
+            // it otherwise. The previous null/undefined pair was half redundant,
+            // which is what the static analysis was pointing at.
+            const query = pageToken ? `?pageToken=${encodeURIComponent(pageToken)}` : '';
+            const page = await this.#http.get(`/v1/revocations${query}`);
+            entries.push(...page.entries);
+            cursor = page.cursor;
+            pageToken = page.nextPageToken;
+        } while (pageToken);
+        this.#set.replaceAll(entries);
+        this.#set.prune();
+        this.#cursor = cursor;
+        this.#synced = true;
+        this.#touch();
+    }
+    /** Follow the Server-Sent Events stream. Returns false if streaming is not usable here. */
+    async #stream() {
+        const response = await this.#http.rawGet(`/v1/revocations/stream?since=${this.#cursor}`, this.#controller?.signal);
+        if (!response.ok)
+            throw httpError(response.status);
+        if (!response.body)
+            return false;
+        const reader = response.body.getReader();
+        this.#reader = reader;
+        const decoder = new TextDecoder();
+        let buffer = '';
+        // A half-open socket delivers nothing and never ends. Heartbeats are due
+        // every second, so silence for twice the staleness bound means the
+        // connection is gone: drop it and let the loop reconnect.
+        const silenceLimit = Math.max(2 * this.#staleAfterMs, 1_000);
+        let watchdog = setTimeout(() => void reader.cancel().catch(() => { }), silenceLimit);
+        watchdog.unref?.();
+        try {
+            while (this.#running) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                clearTimeout(watchdog);
+                watchdog = setTimeout(() => void reader.cancel().catch(() => { }), silenceLimit);
+                watchdog.unref?.();
+                buffer += decoder.decode(value, { stream: true });
+                let index = buffer.indexOf('\n\n');
+                while (index !== -1) {
+                    this.#handleEvent(buffer.slice(0, index));
+                    buffer = buffer.slice(index + 2);
+                    index = buffer.indexOf('\n\n');
+                }
+            }
+        }
+        finally {
+            clearTimeout(watchdog);
+            this.#reader = null;
+            reader.releaseLock();
+            await response.body.cancel().catch(() => { });
+        }
+        return true;
+    }
+    #handleEvent(block) {
+        let event = 'message';
+        let data = '';
+        for (const line of block.split('\n')) {
+            if (line.startsWith('event:'))
+                event = line.slice(6).trim();
+            else if (line.startsWith('data:'))
+                data += line.slice(5).trim();
+        }
+        if (event === 'heartbeat' || event === 'ready') {
+            this.#touch();
+            return;
+        }
+        if (event !== 'revocation' || data.length === 0)
+            return;
+        try {
+            const entry = JSON.parse(data);
+            this.#set.apply(entry);
+            if (entry.seq > this.#cursor)
+                this.#cursor = entry.seq;
+            this.#touch();
+        }
+        catch {
+            // A line we cannot read is not evidence that nothing is revoked; the
+            // next heartbeat decides freshness.
+        }
+    }
+    /** Long-poll fallback for runtimes without streaming response bodies. */
+    async #poll() {
+        const wait = Math.max(1, Math.floor(this.#staleAfterMs / 2 / 1000));
+        while (this.#running) {
+            const page = await this.#http.get(`/v1/revocations?since=${this.#cursor}&wait=${wait}`);
+            this.#set.applyAll(page.entries);
+            if (page.cursor > this.#cursor)
+                this.#cursor = page.cursor;
+            for (const entry of page.entries)
+                if (entry.seq > this.#cursor)
+                    this.#cursor = entry.seq;
+            this.#touch();
+        }
+    }
+}
+function httpError(status) {
+    const error = new Error(`revocation feed responded ${status}`);
+    error.status = status;
+    return error;
+}
+function classify(err) {
+    const status = err?.statusCode
+        ?? err?.status;
+    if (status === 404)
+        return 'disabled';
+    if (status === 503)
+        return 'not_ready';
+    if (status === 401 || status === 403)
+        return 'unauthorized';
+    return 'network';
+}
+async function sleep(ms, signal) {
+    if (signal?.aborted)
+        return;
+    await new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=feed.js.map

package/dist/revocations/feed.js.map

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

package/dist/revocations/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Revocation checking for `enforce()` (PRD G-6).
+ *
+ * - `offline` (default): no check. A revoked grant's token stays
+ *   cryptographically valid until it expires, which is why the other two modes
+ *   exist.
+ * - `feed`: follow the revocation feed and keep an in-memory set of revoked
+ *   grants and tokens. Denies within seconds of a revocation, with no network
+ *   call on the hot path, and fails closed when the feed goes stale.
+ * - `online`: ask the auth service about the grant on every call. Simplest,
+ *   slowest, and denies when the service cannot be reached.
+ */
+export declare const REVOCATION_CHECK_MODES: readonly ['offline', 'online', 'feed'];
+export type RevocationCheckMode = (typeof REVOCATION_CHECK_MODES)[number];
+export declare function isRevocationCheckMode(value: unknown): value is RevocationCheckMode;
+export { RevokedSet } from './set.js';
+export type { CredentialRef, RevocationAction, RevocationEntry, RevocationMatch } from './set.js';
+export { RevocationFeed } from './feed.js';
+export type { FeedUnavailableReason, RevocationFeedOptions, RevocationFeedState } from './feed.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/revocations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/revocations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,YAAI,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAC7E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAElF;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/revocations/index.js

@@ -0,0 +1,19 @@
+/**
+ * Revocation checking for `enforce()` (PRD G-6).
+ *
+ * - `offline` (default): no check. A revoked grant's token stays
+ *   cryptographically valid until it expires, which is why the other two modes
+ *   exist.
+ * - `feed`: follow the revocation feed and keep an in-memory set of revoked
+ *   grants and tokens. Denies within seconds of a revocation, with no network
+ *   call on the hot path, and fails closed when the feed goes stale.
+ * - `online`: ask the auth service about the grant on every call. Simplest,
+ *   slowest, and denies when the service cannot be reached.
+ */
+export const REVOCATION_CHECK_MODES = ['offline', 'online', 'feed'];
+export function isRevocationCheckMode(value) {
+    return typeof value === 'string' && REVOCATION_CHECK_MODES.includes(value);
+}
+export { RevokedSet } from './set.js';
+export { RevocationFeed } from './feed.js';
+//# sourceMappingURL=index.js.map

package/dist/revocations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/revocations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAG7E,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAA4C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpG,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/revocations/set.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the client knows is revoked.
+ *
+ * `enforce()` verifies a grant token offline, so on its own it cannot see a
+ * revocation: the token stays cryptographically valid until it expires. This
+ * set is the answer — a small in-memory index of the grants and tokens the
+ * auth service says are no longer usable, kept current by the revocation feed.
+ */
+export type RevocationAction = 'revoked' | 'suspended' | 'resumed' | 'token_revoked';
+export interface RevocationEntry {
+    seq: number;
+    action: RevocationAction;
+    grantId: string | null;
+    jti: string | null;
+    expiresAt: string | null;
+    at: string;
+}
+export interface CredentialRef {
+    grantId?: string | undefined;
+    tokenId?: string | undefined;
+    parentGrantId?: string | undefined;
+}
+export interface RevocationMatch {
+    /** Which identifier matched: the grant, the token, or the parent grant. */
+    kind: 'grant' | 'token' | 'parent_grant';
+    id: string;
+    action: RevocationAction;
+}
+/** The identifiers a client believes are revoked or suspended, with when they expire. */
+export declare class RevokedSet {
+    #private;
+    get size(): number;
+    /**
+     * Apply one feed entry. `resumed` removes a suspension; a revocation is
+     * never undone, and the auth service never emits `resumed` for one.
+     */
+    apply(entry: RevocationEntry): void;
+    applyAll(entries: readonly RevocationEntry[]): void;
+    /**
+     * Replace everything this set knows with `entries`.
+     *
+     * A snapshot is the complete list of what is revoked or suspended *now*, so
+     * applying one on top of an existing set keeps anything that has since been
+     * resumed. A grant suspended, then resumed while the client was
+     * disconnected, would go on being denied until it expired: the resume
+     * entry passed by while nobody was listening, and the snapshot that
+     * replaced the stream never mentions it.
+     *
+     * Nothing awaits between clearing and refilling, so no caller can observe
+     * an empty set.
+     */
+    replaceAll(entries: readonly RevocationEntry[]): void;
+    /** Why this credential must not be used, or `null` if this set knows nothing against it. */
+    match(ref: CredentialRef, now?: number): RevocationMatch | null;
+    /** Forget entries whose credential has expired; it can no longer be used anyway. */
+    prune(now?: number): void;
+    clear(): void;
+}
+//# sourceMappingURL=set.d.ts.map

package/dist/revocations/set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/revocations/set.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,CAAC;AAErF,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,cAAc,CAAC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,yFAAyF;AACzF,qBAAa,UAAU;;IAIrB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAYlC;IAED,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAElD;IAED;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAGpD;IAED,4FAA4F;IAC5F,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe,GAAG,IAAI,CAW1E;IAED,oFAAoF;IACpF,KAAK,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI,CAGpC;IAED,KAAK,IAAI,IAAI,CAGZ;CACF"}

package/dist/revocations/set.js

@@ -0,0 +1,87 @@
+/**
+ * What the client knows is revoked.
+ *
+ * `enforce()` verifies a grant token offline, so on its own it cannot see a
+ * revocation: the token stays cryptographically valid until it expires. This
+ * set is the answer — a small in-memory index of the grants and tokens the
+ * auth service says are no longer usable, kept current by the revocation feed.
+ */
+/** The identifiers a client believes are revoked or suspended, with when they expire. */
+export class RevokedSet {
+    #grants = new Map();
+    #tokens = new Map();
+    get size() {
+        return this.#grants.size + this.#tokens.size;
+    }
+    /**
+     * Apply one feed entry. `resumed` removes a suspension; a revocation is
+     * never undone, and the auth service never emits `resumed` for one.
+     */
+    apply(entry) {
+        const until = entry.expiresAt === null ? Number.POSITIVE_INFINITY : Date.parse(entry.expiresAt);
+        const valid = Number.isNaN(until) ? Number.POSITIVE_INFINITY : until;
+        if (entry.action === 'resumed') {
+            if (entry.grantId !== null)
+                this.#grants.delete(entry.grantId);
+            return;
+        }
+        if (entry.action === 'token_revoked') {
+            if (entry.jti !== null)
+                this.#tokens.set(entry.jti, { until: valid, action: entry.action });
+            return;
+        }
+        if (entry.grantId !== null)
+            this.#grants.set(entry.grantId, { until: valid, action: entry.action });
+    }
+    applyAll(entries) {
+        for (const entry of entries)
+            this.apply(entry);
+    }
+    /**
+     * Replace everything this set knows with `entries`.
+     *
+     * A snapshot is the complete list of what is revoked or suspended *now*, so
+     * applying one on top of an existing set keeps anything that has since been
+     * resumed. A grant suspended, then resumed while the client was
+     * disconnected, would go on being denied until it expired: the resume
+     * entry passed by while nobody was listening, and the snapshot that
+     * replaced the stream never mentions it.
+     *
+     * Nothing awaits between clearing and refilling, so no caller can observe
+     * an empty set.
+     */
+    replaceAll(entries) {
+        this.clear();
+        this.applyAll(entries);
+    }
+    /** Why this credential must not be used, or `null` if this set knows nothing against it. */
+    match(ref, now = Date.now()) {
+        const grant = ref.grantId === undefined ? undefined : this.#grants.get(ref.grantId);
+        if (grant && grant.until > now)
+            return { kind: 'grant', id: ref.grantId, action: grant.action };
+        const token = ref.tokenId === undefined ? undefined : this.#tokens.get(ref.tokenId);
+        if (token && token.until > now)
+            return { kind: 'token', id: ref.tokenId, action: token.action };
+        // A cascade revokes children too, so a parent entry alone should never
+        // decide a call — but honouring it costs nothing and closes the window
+        // where a child's own entry has not arrived yet.
+        const parent = ref.parentGrantId === undefined ? undefined : this.#grants.get(ref.parentGrantId);
+        if (parent && parent.until > now)
+            return { kind: 'parent_grant', id: ref.parentGrantId, action: parent.action };
+        return null;
+    }
+    /** Forget entries whose credential has expired; it can no longer be used anyway. */
+    prune(now = Date.now()) {
+        for (const [id, entry] of this.#grants)
+            if (entry.until <= now)
+                this.#grants.delete(id);
+        for (const [id, entry] of this.#tokens)
+            if (entry.until <= now)
+                this.#tokens.delete(id);
+    }
+    clear() {
+        this.#grants.clear();
+        this.#tokens.clear();
+    }
+}
+//# sourceMappingURL=set.js.map

package/dist/revocations/set.js.map

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

package/dist/scopes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical Grantex scope-matching semantics (SPEC §4.1).
+ *
+ * A scope is `resource:action[:constraint]`. Matching is exact: a granted
+ * scope satisfies a required scope only when the two strings are identical.
+ * In particular a constrained scope (`payments:initiate:max_500`) is never
+ * satisfied by its unconstrained form, and vice versa — the constraint is
+ * part of the permission, not a suffix to be prefix-matched away.
+ *
+ * Adapters that add their own wildcard sugar MUST reduce to these rules for
+ * every non-wildcard scope (see `@grantex/x402`'s `scopeMatches`).
+ */
+export interface ParsedScope {
+    resource: string;
+    action: string;
+    constraint?: string;
+}
+/** Splits `resource:action[:constraint]`; returns undefined for malformed scopes. */
+export declare function parseScope(scope: string): ParsedScope | undefined;
+/** True when `granted` satisfies `required` — exact string equality. */
+export declare function scopeMatches(granted: string, required: string): boolean;
+/** True when a required scope is satisfied by at least one granted scope. */
+export declare function hasScope(grantedScopes: readonly string[], required: string): boolean;
+/** Required scopes not covered by the granted set (empty when all are satisfied). */
+export declare function missingScopes(grantedScopes: readonly string[], requiredScopes: readonly string[]): string[];
+//# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAOjE;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAC3B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAEV"}

package/dist/scopes.js

@@ -0,0 +1,37 @@
+/**
+ * Canonical Grantex scope-matching semantics (SPEC §4.1).
+ *
+ * A scope is `resource:action[:constraint]`. Matching is exact: a granted
+ * scope satisfies a required scope only when the two strings are identical.
+ * In particular a constrained scope (`payments:initiate:max_500`) is never
+ * satisfied by its unconstrained form, and vice versa — the constraint is
+ * part of the permission, not a suffix to be prefix-matched away.
+ *
+ * Adapters that add their own wildcard sugar MUST reduce to these rules for
+ * every non-wildcard scope (see `@grantex/x402`'s `scopeMatches`).
+ */
+/** Splits `resource:action[:constraint]`; returns undefined for malformed scopes. */
+export function parseScope(scope) {
+    if (typeof scope !== 'string')
+        return undefined;
+    const parts = scope.split(':');
+    if (parts.length < 2 || parts.length > 3)
+        return undefined;
+    if (parts.some((part) => part.length === 0))
+        return undefined;
+    const [resource, action, constraint] = parts;
+    return constraint !== undefined ? { resource, action, constraint } : { resource, action };
+}
+/** True when `granted` satisfies `required` — exact string equality. */
+export function scopeMatches(granted, required) {
+    return typeof granted === 'string' && typeof required === 'string' && granted === required;
+}
+/** True when a required scope is satisfied by at least one granted scope. */
+export function hasScope(grantedScopes, required) {
+    return grantedScopes.some((granted) => scopeMatches(granted, required));
+}
+/** Required scopes not covered by the granted set (empty when all are satisfied). */
+export function missingScopes(grantedScopes, requiredScopes) {
+    return requiredScopes.filter((required) => !hasScope(grantedScopes, required));
+}
+//# sourceMappingURL=scopes.js.map

package/dist/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3D,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,KAAkC,CAAC;IAC1E,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC5F,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAgB;IAC5D,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,QAAQ,CAAC;AAC7F,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,aAAgC,EAAE,QAAgB;IACzE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAC3B,aAAgC,EAChC,cAAiC;IAEjC,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;AACjF,CAAC"}