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

package/src/auth/keys.ts

@@ -0,0 +1,116 @@
+import { sha256 } from "js-sha256";
+import nacl from "tweetnacl";
+
+import { base64urlDecode, base64urlEncode, toArrayBuffer } from "./utils.js";
+
+const ED25519_PKCS8_PREFIX = Uint8Array.from([
+  0x30,
+  0x2e,
+  0x02,
+  0x01,
+  0x00,
+  0x30,
+  0x05,
+  0x06,
+  0x03,
+  0x2b,
+  0x65,
+  0x70,
+  0x04,
+  0x22,
+  0x04,
+  0x20,
+]);
+
+export function pkcs8FromEd25519Seed(seed32: Uint8Array): Uint8Array {
+  if (seed32.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 seed length: ${seed32.length} (expected 32)`,
+    );
+  }
+  const pkcs8 = new Uint8Array(ED25519_PKCS8_PREFIX.length + seed32.length);
+  pkcs8.set(ED25519_PKCS8_PREFIX, 0);
+  pkcs8.set(seed32, ED25519_PKCS8_PREFIX.length);
+  return pkcs8;
+}
+
+function validateEd25519Seed(seed32: Uint8Array): Uint8Array {
+  if (seed32.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 seed length: ${seed32.length} (expected 32)`,
+    );
+  }
+  return seed32;
+}
+
+function ed25519KeyPairFromSeed(seed32: Uint8Array): nacl.SignKeyPair {
+  return nacl.sign.keyPair.fromSeed(validateEd25519Seed(seed32));
+}
+
+export function publicKeyBase64urlFromSeed(seed32: Uint8Array): string {
+  return base64urlEncode(ed25519KeyPairFromSeed(seed32).publicKey);
+}
+
+export function signEd25519SeedDetached(
+  seed32: Uint8Array,
+  data: Uint8Array,
+): Uint8Array {
+  return nacl.sign.detached(data, ed25519KeyPairFromSeed(seed32).secretKey);
+}
+
+export function signEd25519SeedSha256(
+  seed32: Uint8Array,
+  data: Uint8Array,
+): Uint8Array {
+  return signEd25519SeedDetached(
+    seed32,
+    new Uint8Array(sha256.arrayBuffer(data)),
+  );
+}
+
+export async function importEd25519PrivateKeyFromSeedBase64url(
+  seedBase64url: string,
+): Promise<CryptoKey> {
+  const seed = base64urlDecode(seedBase64url);
+  if (seed.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 seed length: ${seed.length} (expected 32)`,
+    );
+  }
+  const pkcs8 = pkcs8FromEd25519Seed(seed);
+  return await crypto.subtle.importKey(
+    "pkcs8",
+    toArrayBuffer(pkcs8),
+    { name: "Ed25519" },
+    true,
+    ["sign"],
+  );
+}
+
+export async function publicKeyBase64urlFromPrivateKey(
+  privateKey: CryptoKey,
+): Promise<string> {
+  const jwk = await crypto.subtle.exportKey("jwk", privateKey) as JsonWebKey;
+  if (typeof jwk.x !== "string" || jwk.x.length === 0) {
+    throw new Error("Failed to derive Ed25519 public key (missing JWK.x)");
+  }
+  return jwk.x;
+}
+
+export async function importEd25519PublicKeyFromBase64url(
+  publicKeyBase64url: string,
+): Promise<CryptoKey> {
+  const raw = base64urlDecode(publicKeyBase64url);
+  if (raw.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 public key length: ${raw.length} (expected 32)`,
+    );
+  }
+  return await crypto.subtle.importKey(
+    "raw",
+    toArrayBuffer(raw),
+    { name: "Ed25519" },
+    true,
+    ["verify"],
+  );
+}

package/src/auth/mod.ts

@@ -0,0 +1,298 @@
+/**
+ * @module
+ *
+ * Trellis server-side authentication library for session-key based authentication.
+ *
+ * - Session keys are Ed25519 keys represented as base64url (32-byte raw public key).
+ * - Proofs are Ed25519 signatures over SHA-256(buildProofInput(...)).
+ * - Services load their session key seed from `TRELLIS_SESSION_KEY_SEED`.
+ */
+
+export {
+  type AuthDeviceUserAuthoritiesListInput,
+  type AuthDeviceUserAuthoritiesListOutput,
+  type AuthDeviceUserAuthoritiesRevokeInput,
+  type AuthDeviceUserAuthoritiesRevokeResponse,
+  type AuthResolveDeviceUserAuthoritiesInput,
+  type AuthResolveDeviceUserAuthoritiesOperation,
+  type AuthResolveDeviceUserAuthoritiesOutput,
+  type AuthResolveDeviceUserAuthoritiesProgress,
+  buildDeviceActivationPayload,
+  buildDeviceWaitProofInput,
+  createDeviceActivationClient,
+  createDeviceNatsAuthToken,
+  deriveDeviceConfirmationCode,
+  deriveDeviceIdentity,
+  deriveDeviceQrMac,
+  type DeviceActivationPayload,
+  type DeviceActivationTransport,
+  type DeviceActivationWaitRequest,
+  type DeviceIdentity,
+  encodeDeviceActivationPayload,
+  getDeviceConnectInfo,
+  type GetDeviceConnectInfoInput,
+  type GetDeviceConnectInfoOutput,
+  parseDeviceActivationPayload,
+  signDeviceWaitRequest,
+  startDeviceActivationRequest,
+  verifyDeviceConfirmationCode,
+  verifyDeviceWaitSignature,
+  waitForDeviceActivation,
+  type WaitForDeviceActivationResponse,
+} from "./device_activation.js";
+export {
+  type AuthConfig,
+  bindFlow,
+  buildLoginUrl,
+  clearSessionKey,
+  createRpcProof,
+  fetchPortalFlowState,
+  generateSessionKey,
+  getOrCreateSessionKey,
+  getPublicSessionKey,
+  hasSessionKey,
+  isBindSuccessResponse,
+  loadSessionKey,
+  natsConnectSigForIat,
+  portalFlowIdFromUrl,
+  portalProviderLoginUrl,
+  portalRedirectLocation,
+  type SessionKeyHandle,
+  type SessionKeyOptions,
+  type SessionKeyPersistenceMode,
+  signBytes,
+  startAuthRequest,
+  submitPortalApproval,
+} from "./browser.js";
+export {
+  buildProofInput,
+  createProof,
+  type ProofParams,
+  verifyProof,
+} from "./proof.js";
+export {
+  ApprovalRecordViewSchema,
+  AuthCapabilitiesListResponseSchema,
+  AuthCapabilitiesListSchema,
+  AuthCapabilityGroupsDeleteResponseSchema,
+  AuthCapabilityGroupsDeleteSchema,
+  AuthCapabilityGroupsGetResponseSchema,
+  AuthCapabilityGroupsGetSchema,
+  AuthCapabilityGroupsListResponseSchema,
+  AuthCapabilityGroupsListSchema,
+  AuthCapabilityGroupsPutResponseSchema,
+  AuthCapabilityGroupsPutSchema,
+  type AuthDeployment,
+  type AuthDeploymentKind,
+  AuthDeploymentKindSchema,
+  AuthDeploymentSchema,
+  AuthDeploymentsCreateResponseSchema,
+  AuthDeploymentsCreateSchema,
+  AuthDeploymentsDisableResponseSchema,
+  AuthDeploymentsDisableSchema,
+  AuthDeploymentsEnableResponseSchema,
+  AuthDeploymentsEnableSchema,
+  AuthDeploymentsListResponseSchema,
+  AuthDeploymentsListSchema,
+  AuthDeploymentsRemoveResponseSchema,
+  AuthDeploymentsRemoveSchema,
+  AuthDevicesConnectInfoGetResponseSchema,
+  AuthDevicesConnectInfoGetSchema,
+  AuthDevicesDisableResponseSchema,
+  AuthDevicesDisableSchema,
+  AuthDevicesEnableResponseSchema,
+  AuthDevicesEnableSchema,
+  AuthDevicesListResponseSchema,
+  AuthDevicesListSchema,
+  AuthDevicesProvisionResponseSchema,
+  AuthDevicesProvisionSchema,
+  AuthDevicesRemoveResponseSchema,
+  AuthDevicesRemoveSchema,
+  AuthDeviceUserAuthoritiesApprovedEventSchema,
+  AuthDeviceUserAuthoritiesListResponseSchema,
+  AuthDeviceUserAuthoritiesListSchema,
+  AuthDeviceUserAuthoritiesRequestedEventSchema,
+  AuthDeviceUserAuthoritiesResolvedEventSchema,
+  AuthDeviceUserAuthoritiesReviewRequestedEventSchema,
+  AuthDeviceUserAuthoritiesReviewsDecideResponseSchema,
+  AuthDeviceUserAuthoritiesReviewsDecideSchema,
+  AuthDeviceUserAuthoritiesReviewsListResponseSchema,
+  AuthDeviceUserAuthoritiesReviewsListSchema,
+  AuthDeviceUserAuthoritiesRevokeResponseSchema,
+  AuthDeviceUserAuthoritiesRevokeSchema,
+  type AuthenticatedDevice,
+  AuthenticatedDeviceSchema,
+  type AuthenticatedService,
+  type AuthenticatedUser,
+  type AuthEnvelopeExpansionsListResponse,
+  AuthEnvelopeExpansionsListResponseSchema,
+  AuthEnvelopeExpansionsListSchema,
+  type AuthEnvelopesApproveRequestResponse,
+  AuthEnvelopesApproveRequestResponseSchema,
+  AuthEnvelopesApproveRequestSchema,
+  type AuthEnvelopesExpandResponse,
+  AuthEnvelopesExpandResponseSchema,
+  AuthEnvelopesExpandSchema,
+  type AuthEnvelopesGetResponse,
+  AuthEnvelopesGetResponseSchema,
+  AuthEnvelopesGetSchema,
+  type AuthEnvelopesGrantOverridesListResponse,
+  AuthEnvelopesGrantOverridesListResponseSchema,
+  AuthEnvelopesGrantOverridesListSchema,
+  AuthEnvelopesGrantOverridesPutSchema,
+  AuthEnvelopesGrantOverridesRemoveSchema,
+  type AuthEnvelopesGrantOverridesResponse,
+  AuthEnvelopesGrantOverridesResponseSchema,
+  type AuthEnvelopesListResponse,
+  AuthEnvelopesListResponseSchema,
+  AuthEnvelopesListSchema,
+  type AuthEnvelopesShrinkResponse,
+  AuthEnvelopesShrinkResponseSchema,
+  AuthEnvelopesShrinkSchema,
+  AuthIdentitiesGrantsListResponseSchema,
+  AuthIdentitiesGrantsListSchema,
+  AuthIdentitiesListResponseSchema,
+  AuthIdentitiesListSchema,
+  AuthIdentityEnvelopesRevokeResponseSchema,
+  AuthIdentityEnvelopesRevokeSchema,
+  AuthPortalsGetResponseSchema,
+  AuthPortalsGetSchema,
+  AuthPortalsListResponseSchema,
+  AuthPortalsListSchema,
+  AuthPortalsLoginSettingsGetSchema,
+  AuthPortalsLoginSettingsResponseSchema,
+  AuthPortalsLoginSettingsUpdateSchema,
+  AuthPortalsRoutesPutResponseSchema,
+  AuthPortalsRoutesPutSchema,
+  AuthPortalsRoutesRemoveResponseSchema,
+  AuthPortalsRoutesRemoveSchema,
+  AuthRequestsValidateResponseSchema,
+  AuthRequestsValidateSchema,
+  AuthResolveDeviceUserAuthoritiesProgressSchema,
+  AuthResolveDeviceUserAuthoritiesResponseSchema,
+  AuthResolveDeviceUserAuthoritiesSchema,
+  AuthServiceInstancesDisableResponseSchema,
+  AuthServiceInstancesDisableSchema,
+  AuthServiceInstancesEnableResponseSchema,
+  AuthServiceInstancesEnableSchema,
+  AuthServiceInstancesListResponseSchema,
+  AuthServiceInstancesListSchema,
+  AuthServiceInstancesProvisionResponseSchema,
+  AuthServiceInstancesProvisionSchema,
+  AuthServiceInstancesRemoveResponseSchema,
+  AuthServiceInstancesRemoveSchema,
+  type AuthSessionsMeResponse,
+  AuthSessionsMeResponseSchema,
+  AuthSessionsMeSchema,
+  AuthUserIdentitiesListResponseSchema,
+  AuthUserIdentitiesListSchema,
+  AuthUserIdentitiesUnlinkResponseSchema,
+  AuthUserIdentitiesUnlinkSchema,
+  AuthUsersAccountFlowCreateResponseSchema,
+  AuthUsersCreateResponseSchema,
+  AuthUsersCreateSchema,
+  AuthUsersGetResponseSchema,
+  AuthUsersGetSchema,
+  AuthUsersIdentityLinkCreateSchema,
+  AuthUsersListResponseSchema,
+  AuthUsersListSchema,
+  AuthUsersPasswordChangeResponseSchema,
+  AuthUsersPasswordChangeSchema,
+  AuthUsersPasswordResetCreateSchema,
+  AuthUsersUpdateResponseSchema,
+  AuthUsersUpdateSchema,
+  CallerViewSchema,
+  ContractAnalysisSchema,
+  ContractAnalysisSummarySchema,
+  DeploymentContractEvidenceSchema,
+  type DeploymentEnvelope,
+  type DeploymentGrantOverride,
+  DeploymentGrantOverrideSchema,
+  DeploymentPortalRouteSchema,
+  DeploymentResourceBindingSchema,
+  type DeviceActivationRecord,
+  DeviceActivationRecordSchema,
+  DeviceActivationReviewSchema,
+  DeviceConnectInfoSchema,
+  DeviceDeploymentSchema,
+  DeviceSchema,
+  DigestSchema,
+  type EnvelopeBoundary,
+  EnvelopeBoundarySchema,
+  EnvelopeExpansionRequestSchema,
+  type FlowRegistrationAvailability,
+  FlowRegistrationAvailabilitySchema,
+  type LoginPortalRecord,
+  LoginPortalRecordSchema,
+  type LoginPortalRoute,
+  LoginPortalRouteSchema,
+  type LoginPortalSettings,
+  LoginPortalSettingsSchema,
+  type LoginPortalSummary,
+  LoginPortalSummarySchema,
+  OpenObjectSchema,
+  type ParticipantKind,
+  ParticipantKindSchema,
+  type PortalFlowApp,
+  type PortalFlowApproval,
+  type PortalFlowApprovalDeniedState,
+  type PortalFlowApprovalRequiredState,
+  type PortalFlowChooseProviderState,
+  type PortalFlowExpiredState,
+  type PortalFlowInsufficientCapabilitiesState,
+  type PortalFlowProvider,
+  type PortalFlowRedirectState,
+  type PortalFlowState,
+  PortalFlowStateSchema,
+  type PortalFlowUser,
+  ServiceDeploymentSchema,
+  ServiceInstanceSchema,
+  UserGrantViewSchema,
+  UserViewSchema,
+  WaitForDeviceActivationRequestSchema,
+  WaitForDeviceActivationResponseSchema,
+} from "./protocol.js";
+export {
+  approvalCapabilityKeys,
+  type ApprovalDecision,
+  ApprovalDecisionSchema,
+  type AuthStartFlowResponse,
+  AuthStartFlowResponseSchema,
+  type AuthStartRequest,
+  AuthStartRequestSchema,
+  type AuthStartResponse,
+  AuthStartResponseSchema,
+  type BindResponse,
+  BindResponseSchema,
+  type BindSuccessResponse,
+  BindSuccessResponseSchema,
+  type ClientTransportEndpoints,
+  ClientTransportEndpointsSchema,
+  type ClientTransports,
+  ClientTransportsSchema,
+  type ContractApproval,
+  type ContractApprovalCapability,
+  ContractApprovalSchema,
+  type NatsAuthTokenV1,
+  NatsAuthTokenV1Schema,
+  type SentinelCreds,
+  SentinelCredsSchema,
+  type UserParticipantKind,
+  UserParticipantKindSchema,
+} from "./schemas.js";
+export {
+  buildNatsConnectSignaturePayload,
+  createAuth,
+  type NatsConnectOptions,
+  type TrellisAuth,
+} from "./session_auth.js";
+export { correctedIatSeconds, estimateMidpointClockOffsetMs } from "./time.js";
+export { trellisIdFromOriginId } from "./trellis_id.js";
+export {
+  base64urlDecode,
+  base64urlEncode,
+  canonicalizeJsonValue,
+  sha256,
+  toArrayBuffer,
+  utf8,
+} from "./utils.js";

package/src/auth/proof.ts

@@ -0,0 +1,111 @@
+import {
+  base64urlDecode,
+  base64urlEncode,
+  sha256,
+  toArrayBuffer,
+  utf8,
+} from "./utils.js";
+import { importEd25519PublicKeyFromBase64url } from "./keys.js";
+import { AsyncResult } from "@qlever-llc/result";
+
+export type ProofParams = {
+  sessionKey: string;
+  subject: string;
+  payloadHash: Uint8Array;
+  iat: number;
+  requestId: string;
+};
+
+function appendLengthPrefixed(
+  buf: Uint8Array,
+  view: DataView,
+  offset: number,
+  value: Uint8Array,
+): number {
+  view.setUint32(offset, value.length);
+  offset += 4;
+  buf.set(value, offset);
+  return offset + value.length;
+}
+
+export function buildProofInput(
+  sessionKey: string,
+  subject: string,
+  payloadHash: Uint8Array,
+  iat: number,
+  requestId: string,
+): Uint8Array {
+  const sessionKeyBytes = utf8(sessionKey);
+  const subjectBytes = utf8(subject);
+  const iatBytes = utf8(String(iat));
+  const requestIdBytes = utf8(requestId);
+
+  const buf = new Uint8Array(
+    4 +
+      sessionKeyBytes.length +
+      4 +
+      subjectBytes.length +
+      4 +
+      payloadHash.length +
+      4 +
+      iatBytes.length +
+      4 +
+      requestIdBytes.length,
+  );
+  const view = new DataView(buf.buffer);
+
+  let offset = 0;
+  offset = appendLengthPrefixed(buf, view, offset, sessionKeyBytes);
+  offset = appendLengthPrefixed(buf, view, offset, subjectBytes);
+  offset = appendLengthPrefixed(buf, view, offset, payloadHash);
+  offset = appendLengthPrefixed(buf, view, offset, iatBytes);
+  appendLengthPrefixed(buf, view, offset, requestIdBytes);
+
+  return buf;
+}
+
+export async function createProof(
+  privateKey: CryptoKey,
+  params: ProofParams,
+): Promise<string> {
+  const input = buildProofInput(
+    params.sessionKey,
+    params.subject,
+    params.payloadHash,
+    params.iat,
+    params.requestId,
+  );
+  const digest = await sha256(input);
+  const sig = await crypto.subtle.sign(
+    { name: "Ed25519" },
+    privateKey,
+    toArrayBuffer(digest),
+  );
+  return base64urlEncode(new Uint8Array(sig));
+}
+
+export async function verifyProof(
+  publicSessionKey: string,
+  params: ProofParams,
+  proofBase64url: string,
+): Promise<boolean> {
+  const result = await AsyncResult.try(async () => {
+    const input = buildProofInput(
+      params.sessionKey,
+      params.subject,
+      params.payloadHash,
+      params.iat,
+      params.requestId,
+    );
+    const digest = await sha256(input);
+    const signature = base64urlDecode(proofBase64url);
+    const pub = await importEd25519PublicKeyFromBase64url(publicSessionKey);
+    return crypto.subtle.verify(
+      { name: "Ed25519" },
+      pub,
+      toArrayBuffer(signature),
+      toArrayBuffer(digest),
+    );
+  });
+  return result.unwrapOr(false);
+}