@oatscenter/trellis 0.100.0-rc.1

package/auth/authorization/nats_registry.js

@@ -0,0 +1,283 @@
+import { AckPolicy, DeliverPolicy, jetstream, jetstreamManager, } from "@nats-io/jetstream";
+import { createInbox } from "@nats-io/nats-core";
+const REVOCATION_PREFIX = "revocation.";
+class RegistryWatchQueue {
+    #values = [];
+    #waiting;
+    #closed = false;
+    #error;
+    push(value) {
+        if (this.#closed)
+            return;
+        if (this.#waiting) {
+            const waiting = this.#waiting;
+            this.#waiting = undefined;
+            waiting.resolve({ done: false, value });
+        }
+        else if (this.#values.length < 2) {
+            this.#values.push(value);
+        }
+        else {
+            throw new Error("authorization revocation watch queue overflow");
+        }
+    }
+    fail(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#error = error;
+        this.#values.length = 0;
+        this.#waiting?.reject(error);
+        this.#waiting = undefined;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#values.length = 0;
+        this.#waiting?.resolve({ done: true, value: undefined });
+        this.#waiting = undefined;
+    }
+    next() {
+        if (this.#error)
+            return Promise.reject(this.#error);
+        if (this.#closed) {
+            return Promise.resolve({ done: true, value: undefined });
+        }
+        const value = this.#values.shift();
+        if (value)
+            return Promise.resolve({ done: false, value });
+        return new Promise((resolve, reject) => this.#waiting = { resolve, reject });
+    }
+}
+/** Connected NATS KV reader for authorization evidence. */
+export class AuthorizationRegistryReader {
+    #nats;
+    #jetstream;
+    #direct;
+    #binding;
+    #inboxPrefix;
+    #contextGets = 0;
+    #watchStarts = 0;
+    constructor(nats, jetstreamClient, direct, binding, inboxPrefix) {
+        this.#nats = nats;
+        this.#jetstream = jetstreamClient;
+        this.#direct = direct;
+        this.#binding = binding;
+        this.#inboxPrefix = inboxPrefix;
+    }
+    /** Open the exact registry buckets from bootstrap-owned internal metadata. */
+    static async open(nats, binding, inboxPrefix) {
+        validateBinding(binding);
+        const manager = await jetstreamManager(nats);
+        return new AuthorizationRegistryReader(nats, jetstream(nats), manager.direct, binding, inboxPrefix);
+    }
+    /** Return a copy of internal registry counters. */
+    ioCounters() {
+        return {
+            contextGets: this.#contextGets,
+            watchStarts: this.#watchStarts,
+        };
+    }
+    /** Read one immutable context by its exact digest key. */
+    async getContext(digest) {
+        assertRegistryKey(digest, "authorization context digest");
+        this.#contextGets += 1;
+        return await this.#putOrNull(this.#binding.contextBucket, digest);
+    }
+    /** Subscribe only to the active context's revocation key. */
+    async watchRevocation(contextDigest) {
+        assertRegistryKey(contextDigest, "authorization context digest");
+        this.#watchStarts += 1;
+        const key = `${REVOCATION_PREFIX}${contextDigest}`;
+        const stream = `KV_${this.#binding.contextBucket}`;
+        const filterSubject = `$KV.${this.#binding.contextBucket}.${key}`;
+        const deliverSubject = createInbox(this.#inboxPrefix);
+        const name = `TrellisAuth${deliverSubject.split(".").at(-1) ?? ""}`;
+        const manager = await this.#jetstream.jetstreamManager();
+        await manager.consumers.add(stream, {
+            ack_policy: AckPolicy.None,
+            deliver_policy: DeliverPolicy.LastPerSubject,
+            deliver_subject: deliverSubject,
+            filter_subject: filterSubject,
+            flow_control: true,
+            idle_heartbeat: 5_000_000_000,
+            inactive_threshold: 10_000_000_000,
+            mem_storage: true,
+            name,
+            num_replicas: 1,
+        });
+        const consumer = await this.#jetstream.consumers.getPushConsumer(stream, name);
+        const queue = new RegistryWatchQueue();
+        let receivedConsumerSequence = 0;
+        let lastStreamRevision = 0;
+        let initialBoundary;
+        let initialized = false;
+        let stopped = false;
+        const initialize = () => {
+            if (!initialized && initialBoundary !== undefined &&
+                receivedConsumerSequence >= initialBoundary) {
+                initialized = true;
+                queue.push({ operation: "initialized" });
+            }
+        };
+        let stop = (error) => {
+            stopped = true;
+            if (error)
+                queue.fail(error);
+            else
+                queue.close();
+        };
+        const messages = await consumer.consume({
+            callback: (message) => {
+                try {
+                    const current = message.info.deliverySequence;
+                    const streamRevision = message.info.streamSequence;
+                    if (message.subject !== filterSubject ||
+                        current !== receivedConsumerSequence + 1 ||
+                        streamRevision <= lastStreamRevision) {
+                        throw new Error("authorization revocation watch sequence gap");
+                    }
+                    receivedConsumerSequence = current;
+                    lastStreamRevision = streamRevision;
+                    const operation = message.headers?.has("KV-Operation")
+                        ? message.headers.get("KV-Operation")
+                        : "PUT";
+                    if (operation === "DEL" || operation === "PURGE") {
+                        queue.push({ operation: "delete", key, revision: streamRevision });
+                    }
+                    else if (operation === "PUT") {
+                        queue.push({
+                            operation: "put",
+                            key,
+                            value: message.data,
+                            revision: streamRevision,
+                        });
+                    }
+                    else {
+                        throw new Error("authorization revocation operation is invalid");
+                    }
+                    initialize();
+                }
+                catch (error) {
+                    stop(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        });
+        stop = (error) => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (error)
+                queue.fail(error);
+            else
+                queue.close();
+            messages.stop(error);
+        };
+        const status = messages.status();
+        const statusTask = (async () => {
+            try {
+                for await (const event of status) {
+                    if (event.type === "heartbeat" &&
+                        event.lastConsumerSequence > receivedConsumerSequence) {
+                        stop(new Error("authorization revocation watch sequence gap"));
+                        return;
+                    }
+                    if (event.type === "heartbeats_missed" ||
+                        event.type === "consumer_deleted" ||
+                        event.type === "stream_not_found" ||
+                        event.type === "consumer_not_found" ||
+                        event.type === "no_responders" ||
+                        event.type === "reset" ||
+                        event.type === "ordered_consumer_recreated") {
+                        stop(new Error(`authorization revocation watch lost coverage: ${event.type}`));
+                        return;
+                    }
+                }
+            }
+            catch (error) {
+                stop(error instanceof Error ? error : new Error(String(error)));
+            }
+            finally {
+                if (!stopped) {
+                    stop(new Error("authorization revocation watch status ended"));
+                }
+            }
+        })();
+        const settled = async () => {
+            await messages.closed();
+            await statusTask;
+        };
+        try {
+            await this.#nats.flush();
+            const info = await consumer.info();
+            initialBoundary = info.delivered.consumer_seq + info.num_pending;
+            initialize();
+        }
+        catch (error) {
+            stop(error instanceof Error ? error : new Error(String(error)));
+            await settled();
+            throw error;
+        }
+        void messages.closed().then((error) => {
+            if (!stopped) {
+                stop(error instanceof Error
+                    ? error
+                    : new Error("authorization revocation watch ended"));
+            }
+        });
+        return {
+            iterator: {
+                next: () => queue.next(),
+                return: async () => {
+                    stop();
+                    await settled();
+                    return { done: true, value: undefined };
+                },
+            },
+            close: async () => {
+                stop();
+                await settled();
+            },
+        };
+    }
+    async #putOrNull(bucket, key) {
+        let entry;
+        try {
+            entry = await this.#direct.getMessage(`KV_${bucket}`, {
+                last_by_subj: `$KV.${bucket}.${key}`,
+            });
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error &&
+                error.code === 404)
+                return null;
+            throw error;
+        }
+        if (!entry)
+            return null;
+        const operation = entry.header?.get("KV-Operation") || "PUT";
+        if (operation !== "PUT") {
+            throw new Error("authorization registry evidence disappeared");
+        }
+        return { value: entry.data, revision: entry.seq, operation };
+    }
+}
+function validateBinding(binding) {
+    const entries = Object.entries(binding);
+    if (entries.length !== 1 || !("contextBucket" in binding)) {
+        throw new Error("authorization registry binding is invalid");
+    }
+    for (const [name, value] of entries) {
+        if (typeof value !== "string" || !value.trim()) {
+            throw new Error(`authorization registry binding ${name} is empty`);
+        }
+    }
+}
+function assertRegistryKey(value, name) {
+    if (!isRegistryKey(value))
+        throw new Error(`${name} is invalid`);
+}
+function isRegistryKey(value) {
+    return value.length === 43 && /^[A-Za-z0-9_-]+$/.test(value);
+}

package/auth/authorization/provider_cache.d.ts

@@ -0,0 +1,90 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import type { AuthorizationVerificationErrorCode, VerifiedAuthorizationContextTokenProjection, VerifiedAuthorizationEventPublisher } from "../protocol_wasm.ts";
+import type { AuthorizationContextCache } from "./client_context.ts";
+import { type AuthorizationRegistryIoCounters } from "./nats_registry.ts";
+import type { AuthorizationProviderEvent, AuthorizationProviderRequest, AuthorizationRegistryBinding } from "./types.ts";
+type VerificationFailure = {
+    ok: false;
+    error: {
+        code: AuthorizationVerificationErrorCode;
+        path: string;
+    };
+};
+type CachedRequestVerificationResult = {
+    ok: true;
+    contextDigest: string;
+    context: VerifiedAuthorizationContextTokenProjection["context"];
+} | VerificationFailure;
+type CachedEventVerificationResult = {
+    ok: true;
+    contextDigest: string;
+    context: VerifiedAuthorizationContextTokenProjection["context"];
+    publisher: VerifiedAuthorizationEventPublisher;
+} | VerificationFailure;
+/** Observable provider registry health. */
+export type AuthorizationProviderCacheHealth = {
+    revocationRevision: number;
+    lastUpdateAt: number;
+    healthy: boolean;
+};
+/** Provider I/O counters used by local hot-path tests and diagnostics. */
+export type AuthorizationProviderIoCounters = AuthorizationRegistryIoCounters & {
+    contextResolves: number;
+    contextVerifications: number;
+};
+/** Internal marker for retryable provider registry or readiness failure. */
+export declare class AuthorizationProviderUnavailableError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/** Provider attach options. */
+export type AuthorizationProviderCacheOptions = {
+    now?: () => number;
+};
+/** Connected provider-side authorization verifier. */
+export declare class AuthorizationProviderCache {
+    #private;
+    private constructor();
+    /** Attach to the bootstrap-selected NATS authorization registry. */
+    static attach(nats: NatsConnection, binding: AuthorizationRegistryBinding, inboxPrefix: string, cache: AuthorizationContextCache, options?: AuthorizationProviderCacheOptions): Promise<AuthorizationProviderCache>;
+    /** Enable provider verification. */
+    start(): void;
+    /** Stop verification without closing the caller-owned NATS connection. */
+    stop(): void;
+    /** Retain exact revocation coverage for the currently installed own context. */
+    retainOwnContext(): Promise<void>;
+    /** Retain candidate coverage on the exact admitted connection generation. */
+    retainOwnCandidate(digest: string, generation: number): Promise<void>;
+    /** Promote the candidate only while its admitted coverage remains current. */
+    promoteOwnCandidate(digest: string, generation: number): void;
+    connectionGeneration(): number;
+    /** Returns whether the current own authorization may authenticate transport. */
+    ownUsable(): boolean;
+    /** A verified private candidate or a retained unrevoked installation may authenticate transport. */
+    transportUsable(): boolean;
+    /** Suspend stale transport authentication and request one current context. */
+    refreshOwnAuthorization(): void;
+    /** React to an authoritative NATS authentication rejection during reconnect. */
+    observeTransportEvent(event: unknown): void;
+    /** Register the connection-owned usability withdrawal for own revocation. */
+    onOwnInvalidated(callback: () => void): void;
+    /** Register the connection-owned resumption after same-context coverage initialization. */
+    onOwnResumed(callback: () => void): void;
+    /** Wait until the connected registry is available. */
+    waitReady(options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Return current provider health. */
+    health(): AuthorizationProviderCacheHealth;
+    /** Return provider and registry I/O counters. */
+    ioCounters(): AuthorizationProviderIoCounters;
+    /** Apply framework-level NATS lifecycle state to provider readiness. */
+    observeConnectionPhase(phase: "connected" | "disconnected" | "reconnecting" | "error" | "closed"): void;
+    /** Resolve one context digest through the connected registry. */
+    resolveContext(contextDigest: string): Promise<VerifiedAuthorizationContextTokenProjection>;
+    /** Verify a presented request proof with exact route permissions. */
+    verifyRequest(request: AuthorizationProviderRequest): Promise<CachedRequestVerificationResult>;
+    /** Verify a presented event proof, including historical issuer evidence. */
+    verifyEvent(event: AuthorizationProviderEvent): Promise<CachedEventVerificationResult>;
+}
+export {};