@oatscenter/trellis 0.100.0-rc.1 → 0.100.0-rc.3

package/auth/admission.d.ts

@@ -0,0 +1,14 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import type { SessionAuthorityOwner } from "./authority.ts";
+import { type AdmissionContext } from "./protocol_wasm.ts";
+import type { TrellisAuth } from "./session_auth.ts";
+/** Obtain exact own-context bytes through the native signed-admission protocol. No application I/O is enabled here. */
+export declare function requestOwnAdmission(options: {
+    nc: NatsConnection;
+    owner: SessionAuthorityOwner;
+    auth: TrellisAuth;
+    runtimeId: string;
+    attachmentId: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<AdmissionContext>;

package/auth/admission.js

@@ -0,0 +1,87 @@
+import { QueuedIteratorImpl } from "@nats-io/nats-core/internal";
+import { ulid } from "ulid";
+import {} from "./protocol_wasm.js";
+import { base64urlDecode, base64urlEncode, sha256, utf8 } from "./utils.js";
+/** Obtain exact own-context bytes through the native signed-admission protocol. No application I/O is enabled here. */
+export async function requestOwnAdmission(options) {
+    const { nc, owner, auth, runtimeId, signal } = options;
+    const deadline = Date.now() + options.timeoutMs;
+    const keyDigest = base64urlEncode(await sha256(base64urlDecode(auth.sessionKey)));
+    const subject = `trellis.auth.admission.${keyDigest}.get`;
+    const reply = `_INBOX.trellis.${keyDigest}.${ulid()}`;
+    const request = {
+        trellisInstanceId: owner.instanceId,
+        runtimeId,
+        sessionPublicKey: auth.sessionKey,
+        attachmentId: options.attachmentId,
+        requestNonce: base64urlEncode(crypto.getRandomValues(new Uint8Array(16))),
+        issuedAt: auth.currentIat(),
+    };
+    const signedRequest = await auth.signAdmissionGet(request, subject, reply);
+    if (signal?.aborted)
+        throw signal.reason;
+    if (Date.now() >= deadline)
+        throw new Error("AdmissionTimeout");
+    const pending = Promise.withResolvers();
+    let settled = false;
+    let verifying = 0;
+    const sub = nc.subscribe(reply, {
+        callback: (error, message) => {
+            if (settled)
+                return;
+            if (error) {
+                pending.reject(error);
+                return;
+            }
+            if (verifying >= 8 || message.data.length > 2 * 1024 * 1024)
+                return;
+            verifying++;
+            void owner
+                .verifyAdmissionContext(message.data, request, subject, reply)
+                .then((response) => {
+                if (settled || signal?.aborted || Date.now() >= deadline)
+                    return;
+                settled = true;
+                pending.resolve(response);
+            })
+                .catch(() => {
+                /* Forged candidates never consume the legitimate pending lookup. */
+            })
+                .finally(() => {
+                verifying--;
+            });
+        },
+    });
+    const statuses = nc.status();
+    if (!(statuses instanceof QueuedIteratorImpl)) {
+        sub.unsubscribe();
+        throw new Error("AdmissionStatusUnavailable");
+    }
+    const statusTask = (async () => {
+        for await (const status of statuses) {
+            if (status.type === "disconnect" || status.type === "close") {
+                pending.reject(new Error("AdmissionDisconnected"));
+                break;
+            }
+        }
+    })().catch((error) => pending.reject(error));
+    const abort = () => pending.reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+    const timer = setTimeout(() => pending.reject(new Error("AdmissionTimeout")), Math.max(0, deadline - Date.now()));
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        if (signal?.aborted)
+            throw signal.reason;
+        nc.publish(subject, utf8(signedRequest), {
+            reply,
+        });
+        return await pending.promise;
+    }
+    finally {
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        sub.unsubscribe();
+        statuses.stop();
+        await statusTask;
+    }
+}

package/auth/authority.d.ts

@@ -0,0 +1,166 @@
+import { type NatsConnection } from "@nats-io/nats-core";
+import { type AdmissionGet, type AdmissionContext, type AuthorityIssuerKey, type AuthenticatedCaller, type CatalogActionIdentity, type OriginalEventPublication, type SessionAuthority, type SessionAuthorityHandle, type SessionAuthorityVerificationPolicy, type SessionEvent, type SessionRequest, type SessionResponse, type IssuerMetadataQuery, type IssuerMetadataResponse } from "./protocol_wasm.ts";
+import { type JsonValue } from "./utils.ts";
+declare const authorityLeaseToken: unique symbol;
+type RecordObject = {
+    [key: string]: JsonValue;
+};
+type CachedAuthority = {
+    /** Private admission candidates cannot serve application frames before commit. */
+    unpublished?: boolean;
+    handle: SessionAuthorityHandle;
+    authority: SessionAuthority;
+    digest: string;
+    references: number;
+    retired: boolean;
+    byteLength: number;
+};
+/** Signed bootstrap registry locations. These are runtime internals, never app authoring input. */
+export type AuthorityRegistryBinding = {
+    materialBucket: string;
+    revocationBucket: string;
+    issuer: AuthorityIssuerKey;
+    rotationSequence: string;
+};
+/** Exact sent request retained until a verified reply or the ordinary timeout. */
+export type PendingSessionRequest = {
+    request: SessionRequest;
+    proofDigest: string;
+    action: CatalogActionIdentity;
+    expectedDeploymentId: string | null;
+};
+/** Short-lived typed identity lease; cannot be constructed from unverified JSON. */
+export declare class VerifiedAuthority {
+    #private;
+    private constructor();
+    /** Only the common owner can lend authenticated state. */
+    static acquire(token: typeof authorityLeaseToken, owner: SessionAuthorityOwner, entry: CachedAuthority): VerifiedAuthority;
+    /** Authenticated fields; no authority is inferred merely from identity. */
+    get authority(): Readonly<SessionAuthority>;
+    /** Content address of the exact immutable signed context. */
+    get digest(): string;
+    /** Whether checked transport publication has released this private candidate. @internal */
+    get published(): boolean;
+    /** Internal verifier access requires the module-private lease token. */
+    entry(token: typeof authorityLeaseToken): CachedAuthority;
+    /** Verified logical caller identity usable by all SDK adapters. */
+    get caller(): AuthenticatedCaller;
+    /** Time and observed retirement are checked again immediately before authorized work. */
+    assertCurrent(): void;
+    /** Authorize a dispatcher action through its actual signed whole-capability membership. */
+    authorize(apiId: string, action: CatalogActionIdentity): Promise<void>;
+    /** Check one action against the verified authority and its exact accepted catalog. */
+    allows(apiId: string, action: CatalogActionIdentity): Promise<boolean>;
+    /** Return authenticated catalog evidence bound to this exact live authority. @internal */
+    authenticatedCatalog(apiId: string): Promise<Readonly<RecordObject> | undefined>;
+    /** Check the Auth-certified implementation, not consumer capability authority. */
+    authorizeProvider(apiId: string, generation: string, action: CatalogActionIdentity): Promise<void>;
+    /** Release local material only; accepted domain work is not rolled back. */
+    release(): void;
+}
+/** Selected installation and current active issuer authenticated by the common authority owner's rotation chain. */
+export type RuntimeAuthorizationTrust = Readonly<{
+    instanceId: string;
+    account: string;
+    issuer: Readonly<AuthorityIssuerKey>;
+    rotationSequence: string;
+}>;
+/** One authority owner per runtime: pinned trust, bounded peer material, one revocation mirror. */
+export declare class SessionAuthorityOwner {
+    #private;
+    readonly instanceId: string;
+    readonly account: string;
+    /** Supply issuer pins from trusted provisioning or selected HTTPS discovery, not peer material. */
+    constructor(options: {
+        instanceId: string;
+        account: string;
+        issuers: readonly AuthorityIssuerKey[];
+        rotationSequence?: string;
+        now?: () => number;
+    });
+    /** Snapshot current authenticated issuer trust and its durable rotation floor; does not discover or advance trust. */
+    get trustSnapshot(): RuntimeAuthorizationTrust;
+    /** Obtain successor trust only from this owner's verified chain rooted at the exact retained credential pin. */
+    trustForCredential(anchor: RuntimeAuthorizationTrust): RuntimeAuthorizationTrust;
+    /** Attach read-only public material and one snapshot-and-update mirror for all logical sessions. */
+    attach(nats: NatsConnection, binding: AuthorityRegistryBinding, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+        inboxPrefix?: string;
+    }): Promise<void>;
+    /** Verify an issuer-signed lookup reply against the actual pending ephemeral request. */
+    verifyAdmissionContext(bytes: Uint8Array, request: AdmissionGet, subject: string, reply: string): Promise<AdmissionContext>;
+    /** Clock and bounds shared by all request/event/provider verification. */
+    policy(): SessionAuthorityVerificationPolicy;
+    /** Install non-evictable own authority only after complete signature, scope, key and lifecycle checks. */
+    get ownDigest(): string | undefined;
+    /** Whether a verified sticky retirement affects the installed own logical session, even while its live lease is unavailable. */
+    get ownRevoked(): boolean;
+    /** Loss of current revocation coverage requiring private snapshot recovery. */
+    get coverageLost(): boolean;
+    /** Verified retirement observed by the runtime's single mirror. */
+    isRevoked(sessionId: string): boolean;
+    /** Observe promotion and sticky lifecycle changes, without a per-context subscription. */
+    subscribeChanges(callback: () => void): () => void;
+    /** Install non-evictable own authority only after complete signature, scope, key and lifecycle checks. */
+    installOwn(bytes: Uint8Array, expected: {
+        runtimeId: string;
+        sessionPublicKey: string;
+        binding?: SessionAuthority["binding"];
+    }): Promise<VerifiedAuthority>;
+    /** Verify a private candidate; commit only at checked transport publication. */
+    prepareOwn(bytes: Uint8Array, expected: {
+        runtimeId: string;
+        sessionPublicKey: string;
+        binding?: SessionAuthority["binding"];
+    }): Promise<{
+        readonly digest: string;
+        readonly authority: Readonly<SessionAuthority>;
+        assertPreparedCurrent(): void;
+        retain(): VerifiedAuthority;
+        commit(): void;
+        dispose(): void;
+    }>;
+    /** Borrow the current own authority, which peer-cache pressure can never evict. */
+    own(): VerifiedAuthority;
+    /** Suspend application intake when the logical transport has no current generation. */
+    setTransportAvailable(available: boolean): void;
+    /** Resolve immutable peer material once per digest, bounded independently from active local identity. */
+    peer(digest: string): Promise<VerifiedAuthority>;
+    /** Authenticate and authorize an exact incoming request without exposing a raw decoded caller. */
+    verifyRequest(request: SessionRequest, payload: Uint8Array, proof: string, action: CatalogActionIdentity, role?: "consumer" | "provider"): Promise<{
+        caller: VerifiedAuthority;
+        requestProofDigest: string;
+    }>;
+    /** Verify actual provider result bytes against the still-pending opening, not response-supplied correlation. */
+    verifyResponse(response: SessionResponse, payload: Uint8Array, proof: string, receivedSubject: string, pending: PendingSessionRequest): Promise<Extract<AuthenticatedCaller["binding"], {
+        kind: "service" | "device";
+    }>>;
+    /** Verify an event live, or at the original trusted JetStream publication rather than replay time. */
+    verifyEvent(event: SessionEvent, payload: Uint8Array, proof: string, action: CatalogActionIdentity, originalPublication?: OriginalEventPublication | null): Promise<AuthenticatedCaller>;
+    /** Apply a verified sticky logical retirement; false mirror records are discarded before any mutation. */
+    observeRevocation(bytes: Uint8Array, expectedSession?: string, originCurrent?: () => boolean): Promise<void>;
+    /** Recheck observed revocation and expiry after every cold asynchronous boundary. */
+    assertCurrent(entry: CachedAuthority): void;
+    /** Shared authorization used by RPC, events and long-lived adapters. */
+    authorize(entry: CachedAuthority, apiId: string, action: CatalogActionIdentity, historical?: boolean, publication?: {
+        at: number;
+        publishedAt?: number;
+    }): Promise<void>;
+    /** Check an advisory action without treating verification failure as ordinary denial. */
+    allows(entry: CachedAuthority, apiId: string, action: CatalogActionIdentity, historical?: boolean, publication?: {
+        at: number;
+        publishedAt?: number;
+    }): Promise<boolean>;
+    /** Resolve immutable catalog evidence for one API bound to a live verified authority. @internal */
+    authenticatedCatalog(entry: CachedAuthority, apiId: string): Promise<Readonly<RecordObject> | undefined>;
+    /** Authenticate the provider certificate and exact advertised action for a retained endpoint. */
+    authorizeProvider(entry: CachedAuthority, apiId: string, generation: string, action: CatalogActionIdentity): Promise<void>;
+    /** Stop owned local work without erasing durable OAuth credentials or published historical material. */
+    stop(): void;
+    /** Read public verification material using a fresh, pinned-issuer authenticated exchange. */
+    readIssuerMetadata(query: IssuerMetadataQuery): Promise<IssuerMetadataResponse>;
+    /** Authenticate one signed successor from this owner's existing durable pin. */
+    acceptIssuerRotation(bytes: Uint8Array): Promise<void>;
+}
+export {};