@oatscenter/trellis 0.100.0-rc.1

package/README.md

@@ -0,0 +1,59 @@
+# @oatscenter/trellis
+
+JavaScript Trellis client runtime. Provides generated-participant client helpers
+and runtime error types.
+
+The npm package contains ESM JavaScript and TypeScript declarations. Use
+`import`; CommonJS output and `require()` support have intentionally been
+removed. Node and Deno adapters remain available as ESM subpaths. JSR
+publication remains supported.
+
+For AI-agent context, start with the generated package `TRELLIS.md` files and
+the raw docs index:
+
+- https://raw.githubusercontent.com/oats-center/trellis/main/docs/static/llms.txt
+- https://raw.githubusercontent.com/oats-center/trellis/main/docs/static/llms-full.txt
+
+```typescript
+import { TrellisClient } from "@oatscenter/trellis";
+import { participants } from "example-trellis";
+
+const client = await TrellisClient.connect({
+  trellisUrl: "https://trellis.example.com",
+  participant: participants.exampleApp.participant,
+}).orThrow();
+```
+
+The local package name comes from `trellis.toml`. Generation emits one ordinary
+ESM package with `apis` and `participants` namespaces, executable JavaScript and
+declarations, and the matching published runtime dependency. Commit that package
+when ordinary builds should not require the Trellis CLI or API cache.
+
+Connected API facades group actions by surface: `.rpc.<group>.<leaf>(input)`,
+`.event.<group>.<leaf>.listen(handler)` or `.publish(event)`,
+`.feed.<group>.<leaf>(input)`, and `.operation.<group>.<leaf>.start(input)`.
+Inspect generated declarations for the exact selected APIs and action names. Do
+not reconstruct transport subjects or use handwritten contract metadata.
+
+Prepared events support durable publish flows. `prepare(...)` returns a
+`PreparedTrellisEvent`; services can persist prepared events in SQL or NATS KV
+outbox repositories and later publish them with `client.publishPrepared(...)`,
+dispatch them with `dispatchOutbox`, or run an `OutboxDispatcher` and call
+`notify()` after an outbox transaction commits.
+
+Durable service event consumption is contract-declared. Add an event consumer
+group to the service contract and call the generated listener with
+`{ group: "groupName" }`. Do not pass `durableName`; Trellis provisions the
+physical JetStream consumer and grants only the bound consumer subjects to the
+service token. Use `{ mode: "ephemeral", replay: "new" }` for live-only
+listeners.
+
+Service connection helpers live in `@oatscenter/trellis/service*` to keep the
+root package browser-safe. Browser login and portal-flow helpers live on
+`@oatscenter/trellis/auth` and `@oatscenter/trellis/auth/browser`.
+
+Service authors should not use the core package to recreate service bootstrap or
+fetch resource bindings. Connect with `TrellisService.connect(...)` from
+`@oatscenter/trellis/service` and use the returned resource handles instead of
+calling `Trellis.Bindings.Get`, constructing `TrellisService` or `StoreHandle`,
+or passing binding/resource data into `Trellis` constructors.

package/auth/authorization/client_context.d.ts

@@ -0,0 +1,61 @@
+import type { AuthorizationContextVerificationPolicy } from "../protocol_wasm.ts";
+import type { AuthorizationContextBundle, AuthorizationContextVerificationMaterial, AuthorizationRoutingMaterial, AuthorizationRuntimeBinding, VerifiedAuthorizationContext } from "./types.ts";
+/** Verifies and exposes the current in-memory authorization context. */
+export declare class AuthorizationContextCache {
+    #private;
+    readonly trellisUrl: string;
+    readonly fetch: typeof globalThis.fetch;
+    readonly now: () => number;
+    constructor(trellisUrl: string, fetch?: typeof globalThis.fetch, now?: () => number);
+    install(bundle: AuthorizationContextBundle, routing: AuthorizationRoutingMaterial, nowUnixSeconds?: number, shouldInstall?: () => boolean, runtime?: AuthorizationRuntimeBinding, installAdditional?: (verified: VerifiedAuthorizationContext) => void | (() => void) | Promise<void | (() => void)>): Promise<VerifiedAuthorizationContext>;
+    /** Verify and retain one private refresh candidate without exposing it to application use. */
+    prepare(bundle: AuthorizationContextBundle, routing: AuthorizationRoutingMaterial, nowUnixSeconds?: number, shouldInstall?: () => boolean, runtime?: AuthorizationRuntimeBinding, installAdditional?: (verified: VerifiedAuthorizationContext) => void | (() => void) | Promise<void | (() => void)>): Promise<VerifiedAuthorizationContext>;
+    /** Promote only the exact prepared candidate after transport admission and own coverage. */
+    promote(expectedDigest: string, shouldInstall?: () => boolean): VerifiedAuthorizationContext;
+    /** Return the installed context identity without time or usability checks. */
+    storedContextDigest(): string | undefined;
+    /** Drop a private candidate that became unusable before promotion. */
+    invalidateCandidate(digest: string): boolean;
+    /** Return the verified candidate used only for transport reauthorization. */
+    transportCurrent(): VerifiedAuthorizationContext;
+    hasCandidate(): boolean;
+    transportRuntimeBinding(): AuthorizationRuntimeBinding;
+    transportRoutingJwt(): string;
+    /** Returns the number of successfully installed authorization contexts. */
+    generation(): number;
+    current(nowUnixSeconds?: number): VerifiedAuthorizationContext;
+    bundle(): AuthorizationContextBundle;
+    /** Return the current compact verifier policy without cloning the context bundle. */
+    verificationPolicy(nowUnixSeconds?: number): AuthorizationContextVerificationPolicy;
+    shouldRefresh(nowUnixSeconds?: number): boolean;
+    clear(): Promise<void>;
+    /** Capture the exact material owned by an in-flight refresh. */
+    clearGuard(): readonly [string | null, string | null, number];
+    /** Clear terminal state only if no newer context or route JWT replaced it. */
+    clearIfCurrent(guard: readonly [string | null, string | null, number]): Promise<boolean>;
+    /** Return reconnect metadata retained with the signed context. */
+    runtimeBinding(): AuthorizationRuntimeBinding;
+    routingJwt(): string;
+    routingRefreshAt(): number;
+    setServerClockOffsetMs(offsetMs: number): void;
+    serverClockOffsetMs(): number;
+    correctedNowSeconds(): number;
+    nowMilliseconds(): number;
+    /**
+     * Return the installed chain material for a provider-side local verifier.
+     *
+     * This is an in-process handoff; it performs no registry I/O.
+     */
+    installedVerificationMaterial(): AuthorizationContextVerificationMaterial;
+    /** Register the single existing refresh task wake callback. */
+    registerRefreshRequest(callback: () => void): () => void;
+    /** Wake the existing refresh task after trust-floor advance. */
+    requestRefresh(): void;
+}
+/** Build the exact policy passed to the Rust/WASM verifier. */
+export declare function authorizationContextVerificationPolicy(policy: AuthorizationContextBundle["policy"], nowUnixSeconds: number): AuthorizationContextVerificationPolicy;
+/** Verify a complete authorization context chain through Rust/WASM. */
+export declare function verifyAuthorizationContext(args: {
+    bundle: AuthorizationContextBundle;
+    policy: AuthorizationContextVerificationPolicy;
+}): Promise<VerifiedAuthorizationContext>;

package/auth/authorization/client_context.js

@@ -0,0 +1,266 @@
+/** Verifies and exposes the current in-memory authorization context. */
+export class AuthorizationContextCache {
+    trellisUrl;
+    fetch;
+    now;
+    #bundle;
+    #verified;
+    #runtime;
+    #routing;
+    #clockOffsetMs = 0;
+    #operation = 0;
+    #generation = 0;
+    #refreshRequest;
+    #refreshRequestPending = false;
+    #candidate;
+    constructor(trellisUrl, fetch = globalThis.fetch, now = Date.now) {
+        this.trellisUrl = trellisUrl;
+        this.fetch = fetch;
+        this.now = now;
+    }
+    async install(bundle, routing, nowUnixSeconds = this.correctedNowSeconds(), shouldInstall = () => true, runtime, installAdditional = () => { }) {
+        const verified = await this.prepare(bundle, routing, nowUnixSeconds, shouldInstall, runtime, installAdditional);
+        return this.promote(verified.contextDigest, shouldInstall);
+    }
+    /** Verify and retain one private refresh candidate without exposing it to application use. */
+    async prepare(bundle, routing, nowUnixSeconds = this.correctedNowSeconds(), shouldInstall = () => true, runtime, installAdditional = () => { }) {
+        const operation = ++this.#operation;
+        const verificationPolicy = authorizationContextVerificationPolicy(bundle.policy, nowUnixSeconds);
+        const verified = await verifyAuthorizationContext({
+            bundle,
+            policy: verificationPolicy,
+        });
+        const nextRuntime = runtime ?? this.#runtime;
+        if (nextRuntime &&
+            (nextRuntime.connectionId !== verified.context.connectionId ||
+                nextRuntime.loginSessionId !== verified.context.loginSessionId ||
+                nextRuntime.participantId !== verified.context.participantId ||
+                nextRuntime.inboxPrefix !== verified.context.inboxPrefix ||
+                !Object.values(nextRuntime.transports).some((transport) => transport.natsServers.length > 0))) {
+            throw new Error("authorization runtime binding does not match signed context");
+        }
+        if (!shouldInstall() || operation !== this.#operation) {
+            throw new Error("authorization context installation stopped");
+        }
+        const nextBundle = structuredClone(bundle);
+        const installedRuntime = nextRuntime
+            ? structuredClone(nextRuntime)
+            : undefined;
+        const nextRouting = structuredClone(routing);
+        const commitAdditional = await installAdditional(verified);
+        if (!shouldInstall() || operation !== this.#operation) {
+            throw new Error("authorization context installation stopped");
+        }
+        this.#candidate = {
+            operation,
+            bundle: nextBundle,
+            verified,
+            runtime: installedRuntime,
+            routing: nextRouting,
+            commitAdditional: typeof commitAdditional === "function"
+                ? commitAdditional
+                : undefined,
+        };
+        return verified;
+    }
+    /** Promote only the exact prepared candidate after transport admission and own coverage. */
+    promote(expectedDigest, shouldInstall = () => true) {
+        const candidate = this.#candidate;
+        if (!candidate || candidate.operation !== this.#operation ||
+            candidate.verified.contextDigest !== expectedDigest || !shouldInstall()) {
+            throw new Error("authorization candidate changed before promotion");
+        }
+        candidate.commitAdditional?.();
+        this.#bundle = candidate.bundle;
+        this.#verified = candidate.verified;
+        this.#runtime = candidate.runtime;
+        this.#routing = candidate.routing;
+        this.#candidate = undefined;
+        this.#generation += 1;
+        return candidate.verified;
+    }
+    /** Return the installed context identity without time or usability checks. */
+    storedContextDigest() {
+        return this.#verified?.contextDigest;
+    }
+    /** Drop a private candidate that became unusable before promotion. */
+    invalidateCandidate(digest) {
+        if (this.#candidate?.verified.contextDigest === digest) {
+            this.#candidate = undefined;
+            return true;
+        }
+        return false;
+    }
+    /** Return the verified candidate used only for transport reauthorization. */
+    transportCurrent() {
+        return this.#candidate?.verified ?? this.current();
+    }
+    hasCandidate() {
+        return this.#candidate !== undefined;
+    }
+    transportRuntimeBinding() {
+        const runtime = this.#candidate?.runtime ?? this.#runtime;
+        if (!runtime) {
+            throw new Error("no authorization runtime metadata is installed");
+        }
+        return structuredClone(runtime);
+    }
+    transportRoutingJwt() {
+        const routing = this.#candidate?.routing ?? this.#routing;
+        if (!routing || routing.bootstrapJwtExpiresAt <= this.correctedNowSeconds())
+            throw new Error("authorization routing JWT expired");
+        return routing.bootstrapJwt;
+    }
+    /** Returns the number of successfully installed authorization contexts. */
+    generation() {
+        return this.#generation;
+    }
+    current(nowUnixSeconds = this.correctedNowSeconds()) {
+        const verified = this.#verified;
+        if (!verified || verified.context.notBefore > nowUnixSeconds ||
+            verified.context.expiresAt <= nowUnixSeconds) {
+            throw new Error("no current authorization context");
+        }
+        return verified;
+    }
+    bundle() {
+        if (!this.#bundle)
+            throw new Error("no authorization context is installed");
+        return structuredClone(this.#bundle);
+    }
+    /** Return the current compact verifier policy without cloning the context bundle. */
+    verificationPolicy(nowUnixSeconds = this.correctedNowSeconds()) {
+        if (!this.#bundle)
+            throw new Error("no authorization context is installed");
+        return authorizationContextVerificationPolicy(this.#bundle.policy, nowUnixSeconds);
+    }
+    shouldRefresh(nowUnixSeconds = this.correctedNowSeconds()) {
+        this.current(nowUnixSeconds);
+        return nowUnixSeconds >= this.routingRefreshAt();
+    }
+    async clear() {
+        this.#operation += 1;
+        this.#bundle = undefined;
+        this.#verified = undefined;
+        this.#routing = undefined;
+        this.#candidate = undefined;
+    }
+    /** Capture the exact material owned by an in-flight refresh. */
+    clearGuard() {
+        return [
+            this.#verified?.contextDigest ?? null,
+            this.#routing?.bootstrapJwt ?? null,
+            this.#operation,
+        ];
+    }
+    /** Clear terminal state only if no newer context or route JWT replaced it. */
+    async clearIfCurrent(guard) {
+        if ((this.#verified?.contextDigest ?? null) !== guard[0] ||
+            (this.#routing?.bootstrapJwt ?? null) !== guard[1] ||
+            this.#operation !== guard[2])
+            return false;
+        this.#operation += 1;
+        this.#bundle = undefined;
+        this.#verified = undefined;
+        this.#routing = undefined;
+        this.#candidate = undefined;
+        return true;
+    }
+    /** Return reconnect metadata retained with the signed context. */
+    runtimeBinding() {
+        if (!this.#runtime) {
+            throw new Error("no authorization runtime metadata is installed");
+        }
+        return structuredClone(this.#runtime);
+    }
+    routingJwt() {
+        if (!this.#routing ||
+            this.#routing.bootstrapJwtExpiresAt <= this.correctedNowSeconds()) {
+            throw new Error("authorization routing JWT expired");
+        }
+        return this.#routing.bootstrapJwt;
+    }
+    routingRefreshAt() {
+        const context = this.current();
+        if (!this.#routing || !this.#bundle)
+            return this.correctedNowSeconds();
+        return Math.min(context.refreshAt, this.#routing.bootstrapJwtExpiresAt -
+            this.#bundle.policy.refreshLeadSeconds);
+    }
+    setServerClockOffsetMs(offsetMs) {
+        this.#clockOffsetMs = offsetMs;
+    }
+    serverClockOffsetMs() {
+        return this.#clockOffsetMs;
+    }
+    correctedNowSeconds() {
+        return Math.floor((this.now() + this.#clockOffsetMs) / 1_000);
+    }
+    nowMilliseconds() {
+        return this.now();
+    }
+    /**
+     * Return the installed chain material for a provider-side local verifier.
+     *
+     * This is an in-process handoff; it performs no registry I/O.
+     */
+    installedVerificationMaterial() {
+        if (!this.#bundle || !this.#verified) {
+            throw new Error("no authorization verification material is installed");
+        }
+        return {
+            issuer: structuredClone(this.#bundle.issuer),
+            context: structuredClone(this.#bundle.context),
+            contextDigest: this.#verified.contextDigest,
+            policy: authorizationContextVerificationPolicy(this.#bundle.policy, this.correctedNowSeconds()),
+            verified: structuredClone(this.#verified),
+        };
+    }
+    /** Register the single existing refresh task wake callback. */
+    registerRefreshRequest(callback) {
+        if (this.#refreshRequest) {
+            throw new Error("authorization refresh callback is already registered");
+        }
+        this.#refreshRequest = callback;
+        if (this.#refreshRequestPending) {
+            this.#refreshRequestPending = false;
+            callback();
+        }
+        return () => {
+            if (this.#refreshRequest === callback)
+                this.#refreshRequest = undefined;
+        };
+    }
+    /** Wake the existing refresh task after trust-floor advance. */
+    requestRefresh() {
+        const callback = this.#refreshRequest;
+        if (callback) {
+            callback();
+        }
+        else {
+            this.#refreshRequestPending = true;
+        }
+    }
+}
+/** Build the exact policy passed to the Rust/WASM verifier. */
+export function authorizationContextVerificationPolicy(policy, nowUnixSeconds) {
+    return {
+        nowUnixSeconds,
+        allowedClockSkewSeconds: policy.allowedClockSkewSeconds,
+        maximumContextLifetimeSeconds: policy.maximumContextLifetimeSeconds,
+        maximumContextBytes: policy.maximumContextBytes,
+        maximumPermissions: policy.maximumPermissions,
+        refreshLeadSeconds: policy.refreshLeadSeconds,
+        refreshJitterSeconds: policy.refreshJitterSeconds,
+    };
+}
+/** Verify a complete authorization context chain through Rust/WASM. */
+export async function verifyAuthorizationContext(args) {
+    const { verifyAuthorizationContextWasm } = await import("../protocol_wasm.js");
+    const result = await verifyAuthorizationContextWasm({
+        issuer: args.bundle.issuer,
+        context: args.bundle.context,
+        policy: args.policy,
+    });
+    return result;
+}

package/auth/authorization/nats_registry.d.ts

@@ -0,0 +1,41 @@
+import { type NatsConnection } from "@nats-io/nats-core";
+import type { AuthorizationRegistryBinding } from "./types.ts";
+/** Registry I/O counters observed since provider-cache start. */
+export type AuthorizationRegistryIoCounters = {
+    contextGets: number;
+    watchStarts: number;
+};
+export type RegistryEntry = {
+    value: Uint8Array;
+    revision: number;
+    operation: string;
+};
+/** One exact revocation-key update observed after subscription flush. */
+export type RegistryWatchEntry = {
+    operation: "put";
+    key: string;
+    value: Uint8Array;
+    revision: number;
+} | {
+    operation: "delete";
+    key: string;
+    revision: number;
+} | {
+    operation: "initialized";
+};
+/** Connected NATS KV reader for authorization evidence. */
+export declare class AuthorizationRegistryReader {
+    #private;
+    private constructor();
+    /** Open the exact registry buckets from bootstrap-owned internal metadata. */
+    static open(nats: NatsConnection, binding: AuthorizationRegistryBinding, inboxPrefix: string): Promise<AuthorizationRegistryReader>;
+    /** Return a copy of internal registry counters. */
+    ioCounters(): AuthorizationRegistryIoCounters;
+    /** Read one immutable context by its exact digest key. */
+    getContext(digest: string): Promise<RegistryEntry | null>;
+    /** Subscribe only to the active context's revocation key. */
+    watchRevocation(contextDigest: string): Promise<{
+        iterator: AsyncIterator<RegistryWatchEntry>;
+        close: () => Promise<void>;
+    }>;
+}