@qlever-llc/trellis 0.8.4 → 0.9.0-rc.10

package/src/auth/schemas.ts

@@ -0,0 +1,145 @@
+import type { StaticDecode } from "typebox";
+import { Type } from "typebox";
+
+const SessionKeySchema = Type.String({
+  pattern: "^[A-Za-z0-9_-]{43}$",
+});
+
+const SignatureSchema = Type.String({
+  pattern: "^[A-Za-z0-9_-]{86}$",
+});
+
+export const ContractDigestSchema = Type.String({
+  pattern: "^[A-Za-z0-9_-]+$",
+});
+
+const OpenObjectSchema = Type.Object({}, { additionalProperties: true });
+
+export const SentinelCredsSchema = Type.Object({
+  jwt: Type.String(),
+  seed: Type.String(),
+});
+
+export type SentinelCreds = StaticDecode<typeof SentinelCredsSchema>;
+
+export const ClientTransportEndpointsSchema = Type.Object({
+  natsServers: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+});
+
+export type ClientTransportEndpoints = StaticDecode<
+  typeof ClientTransportEndpointsSchema
+>;
+
+export const ClientTransportsSchema = Type.Object({
+  native: Type.Optional(ClientTransportEndpointsSchema),
+  websocket: Type.Optional(ClientTransportEndpointsSchema),
+});
+
+export type ClientTransports = StaticDecode<typeof ClientTransportsSchema>;
+
+export const ApprovalDecisionSchema = Type.Union([
+  Type.Literal("approved"),
+  Type.Literal("denied"),
+]);
+
+export type ApprovalDecision = StaticDecode<typeof ApprovalDecisionSchema>;
+
+export const UserParticipantKindSchema = Type.Union([
+  Type.Literal("app"),
+  Type.Literal("agent"),
+]);
+
+export type UserParticipantKind = StaticDecode<
+  typeof UserParticipantKindSchema
+>;
+
+export const ContractApprovalCapabilitySchema = Type.Object({
+  displayName: Type.String(),
+  description: Type.String(),
+  consequence: Type.Optional(Type.String()),
+});
+
+export type ContractApprovalCapability = StaticDecode<
+  typeof ContractApprovalCapabilitySchema
+>;
+
+export const ContractApprovalSchema = Type.Object({
+  contractDigest: ContractDigestSchema,
+  contractId: Type.String(),
+  displayName: Type.String(),
+  description: Type.String(),
+  participantKind: UserParticipantKindSchema,
+  capabilities: Type.Record(Type.String(), ContractApprovalCapabilitySchema),
+});
+
+export type ContractApproval = StaticDecode<typeof ContractApprovalSchema>;
+
+/** Returns the raw global capability keys required by an approval. */
+export function approvalCapabilityKeys(approval: ContractApproval): string[] {
+  return Object.keys(approval.capabilities);
+}
+
+export const BindSuccessResponseSchema = Type.Object({
+  status: Type.Literal("bound"),
+  inboxPrefix: Type.String(),
+  expires: Type.String({ format: "date-time" }),
+  sentinel: SentinelCredsSchema,
+  transports: ClientTransportsSchema,
+});
+
+export const BindInsufficientCapabilitiesResponseSchema = Type.Object({
+  status: Type.Literal("insufficient_capabilities"),
+  approval: ContractApprovalSchema,
+  missingCapabilities: Type.Array(Type.String()),
+  userCapabilities: Type.Array(Type.String()),
+});
+
+export const BindResponseSchema = Type.Union([
+  BindSuccessResponseSchema,
+  BindInsufficientCapabilitiesResponseSchema,
+]);
+
+export type BindResponse = StaticDecode<typeof BindResponseSchema>;
+export type BindSuccessResponse = StaticDecode<
+  typeof BindSuccessResponseSchema
+>;
+export type BindInsufficientCapabilitiesResponse = StaticDecode<
+  typeof BindInsufficientCapabilitiesResponseSchema
+>;
+
+export const AuthStartRequestSchema = Type.Object({
+  provider: Type.Optional(Type.String({ minLength: 1 })),
+  redirectTo: Type.String(),
+  sessionKey: SessionKeySchema,
+  sig: SignatureSchema,
+  contractDigest: Type.Optional(ContractDigestSchema),
+  contract: Type.Optional(OpenObjectSchema),
+  context: Type.Optional(OpenObjectSchema),
+});
+
+export const AuthStartFlowResponseSchema = Type.Object({
+  status: Type.Literal("flow_started"),
+  flowId: Type.String({ minLength: 1 }),
+  loginUrl: Type.String({ minLength: 1 }),
+});
+
+export const AuthStartResponseSchema = Type.Union([
+  BindSuccessResponseSchema,
+  AuthStartFlowResponseSchema,
+]);
+
+export type AuthStartRequest = StaticDecode<typeof AuthStartRequestSchema>;
+export type AuthStartFlowResponse = StaticDecode<
+  typeof AuthStartFlowResponseSchema
+>;
+export type AuthStartResponse = StaticDecode<typeof AuthStartResponseSchema>;
+
+export const NatsAuthTokenV1Schema = Type.Object({
+  v: Type.Literal(1),
+  sessionKey: SessionKeySchema,
+  sig: SignatureSchema,
+  iat: Type.Integer(),
+  contractDigest: ContractDigestSchema,
+});
+
+export type NatsAuthTokenV1 = StaticDecode<typeof NatsAuthTokenV1Schema>;

package/src/auth/session_auth.ts

@@ -0,0 +1,167 @@
+import { type Authenticator } from "@nats-io/nats-core";
+
+import {
+  importEd25519PrivateKeyFromSeedBase64url,
+  publicKeyBase64urlFromSeed,
+  signEd25519SeedSha256,
+} from "./keys.js";
+import { createProof } from "./proof.js";
+import { correctedIatSeconds } from "./time.js";
+import {
+  base64urlDecode,
+  base64urlEncode,
+  canonicalizeJsonValue,
+  sha256,
+  toArrayBuffer,
+  utf8,
+} from "./utils.js";
+import type { NatsAuthTokenV1 } from "./types.js";
+
+export type NatsConnectOptions = {
+  authenticator: Authenticator;
+  inboxPrefix: string;
+};
+
+export type TrellisAuth = {
+  sessionKey: string; // base64url raw public key
+  sign: (data: Uint8Array) => Promise<Uint8Array>;
+  currentIat: () => number;
+  setServerClockOffsetMs: (clockOffsetMs: number) => void;
+
+  oauthInitSig: (
+    redirectTo: string,
+    context?: unknown,
+    provider?: string,
+    contract?: Record<string, unknown>,
+  ) => Promise<string>;
+  bindFlowSig: (flowId: string) => Promise<string>;
+  natsConnectSigForIat: (
+    iat: number,
+    contractDigest: string,
+  ) => Promise<string>;
+
+  createProof: (
+    subject: string,
+    payloadHash: Uint8Array,
+    requestId?: string,
+    iat?: number,
+  ) => Promise<string>;
+  natsConnectOptions: (
+    opts: { contractDigest: string },
+  ) => Promise<NatsConnectOptions>;
+};
+
+/**
+ * Builds the canonical value signed for NATS runtime-auth tokens.
+ */
+export function buildNatsConnectSignaturePayload(
+  iat: number,
+  contractDigest: string,
+): string {
+  return `${iat}:${contractDigest}`;
+}
+
+export async function createAuth(
+  opts: { sessionKeySeed: string },
+): Promise<TrellisAuth> {
+  const seed = base64urlDecode(opts.sessionKeySeed);
+  const privateKey = await importEd25519PrivateKeyFromSeedBase64url(
+    opts.sessionKeySeed,
+  );
+  const sessionKey = publicKeyBase64urlFromSeed(seed);
+  let serverClockOffsetMs = 0;
+
+  const sign = async (data: Uint8Array): Promise<Uint8Array> => {
+    const sig = await crypto.subtle.sign(
+      { name: "Ed25519" },
+      privateKey,
+      toArrayBuffer(data),
+    );
+    return new Uint8Array(sig);
+  };
+
+  const signDomainHash = async (
+    prefix: string,
+    value: string,
+  ): Promise<string> => {
+    const digest = await sha256(utf8(`${prefix}:${value}`));
+    const sigBytes = await sign(digest);
+    return base64urlEncode(sigBytes);
+  };
+
+  const signOauthInit = async (
+    redirectTo: string,
+    context?: unknown,
+    provider?: string,
+    contract?: Record<string, unknown>,
+  ): Promise<string> => {
+    const canonicalContext = canonicalizeJsonValue(context ?? null);
+    const payload = contract === undefined
+      ? `${redirectTo}:${canonicalContext}`
+      : `${redirectTo}:${provider ?? ""}:${
+        canonicalizeJsonValue(contract)
+      }:${canonicalContext}`;
+    return await signDomainHash("oauth-init", payload);
+  };
+
+  const buildServiceNatsAuthToken = (
+    iat: number,
+    contractDigest: string,
+  ): NatsAuthTokenV1 => {
+    return {
+      v: 1,
+      sessionKey,
+      iat,
+      contractDigest,
+      sig: base64urlEncode(
+        signEd25519SeedSha256(
+          seed,
+          utf8(
+            `nats-connect:${
+              buildNatsConnectSignaturePayload(iat, contractDigest)
+            }`,
+          ),
+        ),
+      ),
+    };
+  };
+
+  const currentIat = (): number =>
+    correctedIatSeconds(Date.now(), serverClockOffsetMs);
+
+  return {
+    sessionKey,
+    sign,
+    currentIat,
+    setServerClockOffsetMs: (clockOffsetMs) => {
+      serverClockOffsetMs = clockOffsetMs;
+    },
+    oauthInitSig: signOauthInit,
+    bindFlowSig: (flowId) => signDomainHash("bind-flow", flowId),
+    natsConnectSigForIat: (iat, contractDigest) =>
+      signDomainHash(
+        "nats-connect",
+        buildNatsConnectSignaturePayload(iat, contractDigest),
+      ),
+    createProof: (subject, payloadHash, requestId = crypto.randomUUID(), iat) =>
+      createProof(privateKey, {
+        sessionKey,
+        subject,
+        payloadHash,
+        iat: iat ?? currentIat(),
+        requestId,
+      }),
+    natsConnectOptions: async (options) => {
+      return {
+        authenticator: () => {
+          const authToken = buildServiceNatsAuthToken(
+            currentIat(),
+            options.contractDigest,
+          );
+          return { auth_token: JSON.stringify(authToken) };
+        },
+        inboxPrefix: `_INBOX.${sessionKey.slice(0, 16)}`,
+      };
+    },
+  };
+}

package/src/auth/time.ts

@@ -0,0 +1,15 @@
+export function estimateMidpointClockOffsetMs(args: {
+  requestStartedAtMs: number;
+  responseReceivedAtMs: number;
+  serverNowSeconds: number;
+}): number {
+  const midpointMs = (args.requestStartedAtMs + args.responseReceivedAtMs) / 2;
+  return args.serverNowSeconds * 1_000 - midpointMs;
+}
+
+export function correctedIatSeconds(
+  nowMs: number = Date.now(),
+  clockOffsetMs: number = 0,
+): number {
+  return Math.floor((nowMs + clockOffsetMs) / 1_000);
+}

package/src/auth/trellis_id.ts

@@ -0,0 +1,9 @@
+import { base64urlEncode, sha256, utf8 } from "./utils.js";
+
+export async function trellisIdFromOriginId(
+  origin: string,
+  id: string,
+): Promise<string> {
+  const digest = await sha256(utf8(`${origin}:${id}`));
+  return base64urlEncode(digest).slice(0, 22);
+}

package/src/auth/types.ts

@@ -0,0 +1,4 @@
+import type { StaticDecode } from "typebox";
+import { NatsAuthTokenV1Schema } from "./schemas.js";
+
+export type NatsAuthTokenV1 = StaticDecode<typeof NatsAuthTokenV1Schema>;

package/src/auth/utils.ts

@@ -0,0 +1,87 @@
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+export function canonicalizeJson(value: JsonValue): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return JSON.stringify(value);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalizeJson).join(",")}]`;
+  }
+
+  const keys = Object.keys(value).sort();
+  return `{${
+    keys.map((key) =>
+      `${JSON.stringify(key)}:${canonicalizeJson(value[key] as JsonValue)}`
+    ).join(",")
+  }}`;
+}
+
+export function toArrayBuffer(data: Uint8Array): ArrayBuffer {
+  const buf = data.buffer;
+  if (buf instanceof ArrayBuffer) {
+    return buf.slice(data.byteOffset, data.byteOffset + data.byteLength);
+  }
+  const copy = new Uint8Array(data.byteLength);
+  copy.set(data);
+  return copy.buffer;
+}
+
+export function base64urlEncode(data: Uint8Array): string {
+  const b64 = btoa(String.fromCharCode(...data));
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+export function base64urlDecode(s: string): Uint8Array {
+  const normalized = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (normalized.length % 4)) % 4;
+  const padded = normalized + "=".repeat(padLen);
+  const bin = atob(padded);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export async function sha256(data: Uint8Array): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(data));
+  return new Uint8Array(digest);
+}
+
+function canonicalizeUnknownJsonValue(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("JSON numbers must be finite");
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalizeUnknownJsonValue).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${
+      keys.map((key) =>
+        `${JSON.stringify(key)}:${
+          canonicalizeUnknownJsonValue((value as Record<string, unknown>)[key])
+        }`
+      ).join(",")
+    }}`;
+  }
+
+  throw new Error("Value is not JSON-serializable");
+}
+
+export function canonicalizeJsonValue(value: unknown): string {
+  return canonicalizeUnknownJsonValue(value);
+}

package/src/auth.ts

@@ -0,0 +1,2 @@
+import "./_dnt.polyfills.js";
+export * from "./auth/mod.js";

package/src/browser.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe compatibility alias for @qlever-llc/trellis.
+ */
+import "./_dnt.polyfills.js";
+
+
+export * from "./index.js";
+export type { TrellisAuth } from "./trellis.js";

package/src/client.ts

@@ -0,0 +1,164 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { CONTRACT_STATE_METADATA } from "./contract_support/mod.js";
+import type { ContractStateMetadata } from "./contract_support/mod.js";
+import type { TrellisAPI } from "./contracts.js";
+
+import type { LoggerLike } from "./globals.js";
+import type { RuntimeStateStoresForContract, TrellisAuth } from "./trellis.js";
+import { Trellis } from "./trellis.js";
+
+type CoreSdkModule = {
+  API?: {
+    trellis?: TrellisAPI;
+  };
+  core?: {
+    API: {
+      trellis: TrellisAPI;
+    };
+  };
+};
+
+type NoResponderRetryOpts = {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+};
+
+export type ClientOpts = {
+  /**
+   * Logical name for this client instance (used for logs and consumer names).
+   * Defaults to "client".
+   */
+  name?: string;
+  log?: LoggerLike;
+  timeout?: number;
+  stream?: string;
+  noResponderRetry?: NoResponderRetryOpts;
+};
+
+type ClientContract<TApi, TContract> = {
+  CONTRACT: TContract;
+  API: {
+    owned?: TApi;
+    trellis?: TApi;
+  };
+  readonly [CONTRACT_STATE_METADATA]?: ContractStateMetadata;
+};
+
+type ClientContractManifest = {
+  state?: Readonly<Record<string, unknown>>;
+  schemas?: Readonly<Record<string, unknown>>;
+};
+
+type ClientContractShape = {
+  CONTRACT: ClientContractManifest;
+  API: {
+    owned?: TrellisAPI;
+    trellis?: TrellisAPI;
+  };
+  readonly [CONTRACT_STATE_METADATA]?: ContractStateMetadata;
+};
+
+type ClientContractForApi<TApi extends TrellisAPI> = ClientContract<
+  TApi,
+  ClientContractManifest
+>;
+
+type ApiForClientContract<TContract extends ClientContractShape> =
+  TContract extends { API: { trellis: infer TApi } }
+    ? TApi extends TrellisAPI ? TApi : never
+    : TContract extends { API: { owned: infer TApi } }
+      ? TApi extends TrellisAPI ? TApi : never
+    : never;
+
+/**
+ * Create a Trellis client typed from a contract module's derived outbound surface.
+ */
+export function createClient<TContract extends ClientContractShape>(
+  contract: TContract,
+  nats: NatsConnection,
+  auth: TrellisAuth,
+  opts?: ClientOpts,
+): Trellis<
+  ApiForClientContract<TContract>,
+  "client",
+  RuntimeStateStoresForContract<TContract>
+>;
+export function createClient<
+  TApi extends TrellisAPI,
+  TContract extends ClientContractForApi<TApi> = ClientContractForApi<TApi>,
+>(
+  contract: TContract,
+  nats: NatsConnection,
+  auth: TrellisAuth,
+  opts?: ClientOpts,
+): Trellis<TApi, "client", RuntimeStateStoresForContract<TContract>>;
+export function createClient<
+  TContract extends ClientContractShape,
+>(
+  contract: TContract,
+  nats: NatsConnection,
+  auth: TrellisAuth,
+  opts?: ClientOpts,
+): unknown {
+  const api = contract.API.trellis ?? contract.API.owned;
+  if (!api) {
+    throw new Error("Contract is missing an owned or trellis API view");
+  }
+
+  return new Trellis<
+    TrellisAPI,
+    "client",
+    RuntimeStateStoresForContract<ClientContractShape>
+  >(
+    opts?.name ?? "client",
+    nats,
+    auth,
+    {
+      log: opts?.log,
+      timeout: opts?.timeout,
+      stream: opts?.stream,
+      noResponderRetry: opts?.noResponderRetry,
+      api,
+      state: contract[CONTRACT_STATE_METADATA],
+    },
+  );
+}
+
+async function loadCoreApi(): Promise<TrellisAPI> {
+  try {
+    const mod = await import("./sdk/core.js") as CoreSdkModule;
+    const api = mod.core?.API.trellis ?? mod.API?.trellis;
+    if (api) {
+      return api;
+    }
+  } catch (error) {
+    throw new Error(
+      "Failed to load the Trellis core SDK. Generate the core SDK first or use createClient(contract, ...) with an explicit contract API.",
+      { cause: error },
+    );
+  }
+
+  throw new Error(
+    "Failed to load the Trellis core SDK API surface. Use createClient(contract, ...) with an explicit contract API if you do not need the generated core SDK.",
+  );
+}
+
+export async function createCoreClient(
+  nats: NatsConnection,
+  auth: TrellisAuth,
+  opts?: ClientOpts,
+): Promise<Trellis<TrellisAPI>> {
+  const api = await loadCoreApi();
+  return new Trellis<TrellisAPI>(
+    opts?.name ?? "client",
+    nats,
+    auth,
+    {
+      log: opts?.log,
+      timeout: opts?.timeout,
+      stream: opts?.stream,
+      noResponderRetry: opts?.noResponderRetry,
+      api,
+    },
+  );
+}