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

package/src/auth/browser/session.ts

@@ -0,0 +1,197 @@
+import {
+  base64urlEncode,
+  canonicalizeJsonValue,
+  sha256,
+  toArrayBuffer,
+  utf8,
+} from "../utils.js";
+import { createProof } from "../proof.js";
+import { buildNatsConnectSignaturePayload } from "../session_auth.js";
+import {
+  deleteKeyPair,
+  hasKeyPair,
+  loadKeyPair,
+  storeKeyPair,
+} from "./storage.js";
+
+export type SessionKeyHandle = {
+  privateKey: CryptoKey;
+  publicKey: CryptoKey;
+  publicKeyRaw: Uint8Array;
+  sessionKey: string;
+  persistence?: SessionKeyPersistenceMode;
+  expiresAt?: number;
+};
+
+export type SessionKeyPersistenceMode = "temporary" | "remembered";
+
+export type SessionKeyOptions = {
+  /** Defaults to remembered IndexedDB storage. */
+  persistence?: SessionKeyPersistenceMode;
+  /** Expiry for remembered keys, as epoch milliseconds or a Date. */
+  expiresAt?: number | Date;
+  /** Relative expiry for remembered keys. Ignored when expiresAt is set. */
+  ttlMs?: number;
+};
+
+let temporarySessionKey: SessionKeyHandle | null = null;
+
+function resolveExpiresAt(options: SessionKeyOptions): number | undefined {
+  if (options.expiresAt instanceof Date) return options.expiresAt.getTime();
+  if (typeof options.expiresAt === "number") return options.expiresAt;
+  if (typeof options.ttlMs === "number") return Date.now() + options.ttlMs;
+  return undefined;
+}
+
+export async function generateSessionKey(
+  options: SessionKeyOptions = {},
+): Promise<SessionKeyHandle> {
+  const persistence = options.persistence ?? "remembered";
+  const expiresAt = resolveExpiresAt(options);
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "Ed25519" },
+    false,
+    ["sign", "verify"],
+  ) as CryptoKeyPair;
+
+  const publicKeyRaw = new Uint8Array(
+    await crypto.subtle.exportKey("raw", keyPair.publicKey),
+  );
+  const sessionKey = base64urlEncode(publicKeyRaw);
+
+  const handle: SessionKeyHandle = {
+    privateKey: keyPair.privateKey,
+    publicKey: keyPair.publicKey,
+    publicKeyRaw,
+    sessionKey,
+    persistence,
+    ...(expiresAt === undefined ? {} : { expiresAt }),
+  };
+
+  if (persistence === "temporary") {
+    temporarySessionKey = handle;
+  } else {
+    await storeKeyPair(keyPair, publicKeyRaw, { expiresAt });
+  }
+
+  return handle;
+}
+
+export async function loadSessionKey(
+  options: Pick<SessionKeyOptions, "persistence"> = {},
+): Promise<SessionKeyHandle | null> {
+  const persistence = options.persistence ?? "remembered";
+  if (persistence === "temporary") return temporarySessionKey;
+  const stored = await loadKeyPair();
+  if (!stored) return null;
+  return {
+    privateKey: stored.privateKey,
+    publicKey: stored.publicKey,
+    publicKeyRaw: stored.publicKeyRaw,
+    sessionKey: base64urlEncode(stored.publicKeyRaw),
+    persistence: "remembered",
+    ...(stored.expiresAt === undefined ? {} : { expiresAt: stored.expiresAt }),
+  };
+}
+
+export async function getOrCreateSessionKey(
+  options: SessionKeyOptions = {},
+): Promise<SessionKeyHandle> {
+  const existing = await loadSessionKey(options);
+  if (existing) return existing;
+  return await generateSessionKey(options);
+}
+
+export async function signBytes(
+  handle: SessionKeyHandle,
+  data: Uint8Array,
+): Promise<Uint8Array> {
+  const sig = await crypto.subtle.sign(
+    { name: "Ed25519" },
+    handle.privateKey,
+    toArrayBuffer(data),
+  );
+  return new Uint8Array(sig);
+}
+
+export function getPublicSessionKey(handle: SessionKeyHandle): string {
+  return handle.sessionKey;
+}
+
+export async function oauthInitSig(
+  handle: SessionKeyHandle,
+  redirectTo: string,
+  context?: unknown,
+  provider?: string,
+  contract?: Record<string, unknown> | string,
+): Promise<string> {
+  const canonicalContext = canonicalizeJsonValue(context ?? null);
+  const payload = contract === undefined
+    ? `${redirectTo}:${canonicalContext}`
+    : `${redirectTo}:${provider ?? ""}:${
+      canonicalizeJsonValue(contract)
+    }:${canonicalContext}`;
+  const digest = await sha256(utf8(`oauth-init:${payload}`));
+  const sig = await signBytes(handle, digest);
+  return base64urlEncode(sig);
+}
+
+export async function bindFlowSig(
+  handle: SessionKeyHandle,
+  flowId: string,
+): Promise<string> {
+  const digest = await sha256(utf8(`bind-flow:${flowId}`));
+  const sig = await signBytes(handle, digest);
+  return base64urlEncode(sig);
+}
+
+export async function natsConnectSigForIat(
+  handle: SessionKeyHandle,
+  iat: number,
+  contractDigest: string,
+): Promise<string> {
+  const digest = await sha256(
+    utf8(
+      `nats-connect:${buildNatsConnectSignaturePayload(iat, contractDigest)}`,
+    ),
+  );
+  const sig = await signBytes(handle, digest);
+  return base64urlEncode(sig);
+}
+
+export async function createRpcProof(
+  handle: SessionKeyHandle,
+  subject: string,
+  payload: Uint8Array,
+  requestId: string,
+  iat: number,
+): Promise<string> {
+  const payloadHash = await sha256(payload);
+  return await createProof(handle.privateKey, {
+    sessionKey: handle.sessionKey,
+    subject,
+    payloadHash,
+    iat,
+    requestId,
+  });
+}
+
+export async function clearSessionKey(
+  options: Pick<SessionKeyOptions, "persistence"> = {},
+): Promise<void> {
+  const persistence = options.persistence;
+  if (persistence === undefined || persistence === "temporary") {
+    temporarySessionKey = null;
+  }
+  if (persistence === undefined || persistence === "remembered") {
+    await deleteKeyPair();
+  }
+}
+
+export async function hasSessionKey(
+  options: Pick<SessionKeyOptions, "persistence"> = {},
+): Promise<boolean> {
+  const persistence = options.persistence ?? "remembered";
+  if (persistence === "temporary") return temporarySessionKey !== null;
+  return await hasKeyPair();
+}

package/src/auth/browser/storage.ts

@@ -0,0 +1,105 @@
+const DB_NAME = "trellis-auth";
+const DB_VERSION = 1;
+const STORE_NAME = "keys";
+const KEY_ID = "trellis-session-key";
+
+function openDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => resolve(request.result);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME, { keyPath: "id" });
+      }
+    };
+  });
+}
+
+export type StoredKeyPair = {
+  id: string;
+  privateKey: CryptoKey;
+  publicKey: CryptoKey;
+  publicKeyRaw: Uint8Array;
+  createdAt: number;
+  persistence?: "remembered";
+  expiresAt?: number;
+};
+
+export type StoredKeyPairOptions = {
+  expiresAt?: number;
+};
+
+export async function storeKeyPair(
+  keyPair: CryptoKeyPair,
+  publicKeyRaw: Uint8Array,
+  options: StoredKeyPairOptions = {},
+): Promise<void> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+
+    const record: StoredKeyPair = {
+      id: KEY_ID,
+      privateKey: keyPair.privateKey,
+      publicKey: keyPair.publicKey,
+      publicKeyRaw,
+      createdAt: Date.now(),
+      persistence: "remembered",
+      ...(options.expiresAt === undefined
+        ? {}
+        : { expiresAt: options.expiresAt }),
+    };
+
+    const request = store.put(record);
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => resolve();
+
+    tx.oncomplete = () => db.close();
+  });
+}
+
+export async function loadKeyPair(): Promise<StoredKeyPair | null> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+
+    const request = store.get(KEY_ID);
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => {
+      const result = request.result as StoredKeyPair | undefined;
+      if (result?.expiresAt !== undefined && result.expiresAt <= Date.now()) {
+        store.delete(KEY_ID);
+        resolve(null);
+        return;
+      }
+      resolve(result ?? null);
+    };
+
+    tx.oncomplete = () => db.close();
+  });
+}
+
+export async function deleteKeyPair(): Promise<void> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+
+    const request = store.delete(KEY_ID);
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => resolve();
+
+    tx.oncomplete = () => db.close();
+  });
+}
+
+export async function hasKeyPair(): Promise<boolean> {
+  const keyPair = await loadKeyPair();
+  return keyPair !== null;
+}

package/src/auth/browser.ts

@@ -0,0 +1,82 @@
+/**
+ * @module
+ * Browser-based authentication utilities for session-key based authentication.
+ * Uses WebCrypto API and IndexedDB for secure key storage.
+ */
+import "../_dnt.polyfills.js";
+
+
+export {
+  type AuthConfig,
+  type AuthStartFlowResponse,
+  type AuthStartRequest,
+  type AuthStartResponse,
+  bindFlow,
+  type BindResponse,
+  type BindSuccessResponse,
+  buildLoginUrl,
+  isBindSuccessResponse,
+  type SentinelCreds,
+  startAuthRequest,
+} from "./browser/login.js";
+export {
+  type ApprovalDecision,
+  fetchPortalFlowState,
+  portalFlowIdFromUrl,
+  type PortalFlowState,
+  type PortalFlowState as BrowserPortalFlowState,
+  portalProviderLoginUrl,
+  portalRedirectLocation,
+  submitPortalApproval,
+} from "./browser/portal.js";
+export {
+  bindFlowSig,
+  clearSessionKey,
+  createRpcProof,
+  generateSessionKey,
+  getOrCreateSessionKey,
+  getPublicSessionKey,
+  hasSessionKey,
+  loadSessionKey,
+  natsConnectSigForIat,
+  type SessionKeyHandle,
+  type SessionKeyOptions,
+  type SessionKeyPersistenceMode,
+  signBytes,
+} from "./browser/session.js";
+export { deleteKeyPair, hasKeyPair } from "./browser/storage.js";
+export {
+  approvalCapabilityKeys,
+  type ApprovalDecision as ApprovalDecisionData,
+  ApprovalDecisionSchema,
+  type AuthStartFlowResponse as AuthStartFlowResponseData,
+  AuthStartFlowResponseSchema,
+  type AuthStartRequest as AuthStartRequestData,
+  AuthStartRequestSchema,
+  type AuthStartResponse as AuthStartResponseData,
+  AuthStartResponseSchema,
+  type BindResponse as BindResponseData,
+  BindResponseSchema,
+  type BindSuccessResponse as BindSuccessResponseData,
+  BindSuccessResponseSchema,
+  type ClientTransportEndpoints as ClientTransportEndpointsData,
+  ClientTransportEndpointsSchema,
+  type ClientTransports as ClientTransportsData,
+  ClientTransportsSchema,
+  type ContractApproval as ContractApprovalData,
+  type ContractApprovalCapability as ContractApprovalCapabilityData,
+  ContractApprovalSchema,
+  type NatsAuthTokenV1 as NatsAuthTokenV1Data,
+  NatsAuthTokenV1Schema,
+  type SentinelCreds as SentinelCredsData,
+  SentinelCredsSchema,
+} from "./schemas.js";
+
+export type { NatsAuthTokenV1 } from "./types.js";
+export {
+  base64urlDecode,
+  base64urlEncode,
+  sha256,
+  toArrayBuffer,
+  utf8,
+} from "./utils.js";