gitspace 0.2.0-rc.1

package/src/lib/tmux-lite/crypto/invites.test.ts

@@ -0,0 +1,381 @@
+/**
+ * Tests for invite token creation and verification
+ */
+
+import { describe, it, expect } from "bun:test";
+import { ed25519, x25519 } from "@noble/curves/ed25519.js";
+import type { Identity } from "../../../types/identity.js";
+import {
+  createInviteToken,
+  parseInviteToken,
+  getPublicIdentityFromInvite,
+  isInviteExpired,
+} from "./invites.js";
+
+/**
+ * Create a mock machine identity for testing
+ */
+function createMockIdentity(label = "test-machine"): Identity {
+  // Generate Ed25519 keypair for signing
+  const signingKeypair = ed25519.keygen();
+
+  // Generate X25519 keypair for key exchange
+  const keyExchangeKeypair = x25519.keygen();
+
+  // Create Ed25519 secret key (64 bytes: 32 private + 32 public)
+  const secretKey = new Uint8Array(64);
+  secretKey.set(signingKeypair.secretKey, 0);
+  secretKey.set(signingKeypair.publicKey, 32);
+
+  const id = Buffer.from(signingKeypair.publicKey)
+    .toString("base64url")
+    .slice(0, 16);
+
+  return {
+    id,
+    signing: {
+      publicKey: signingKeypair.publicKey,
+      secretKey,
+    },
+    keyExchange: {
+      publicKey: keyExchangeKeypair.publicKey,
+      privateKey: keyExchangeKeypair.secretKey,
+    },
+    label,
+    createdAt: Date.now(),
+  };
+}
+
+describe("invites", () => {
+  describe("createInviteToken", () => {
+    it("creates a valid base64url-encoded token", () => {
+      const identity = createMockIdentity();
+      const token = createInviteToken(identity, "wss://relay.example.com");
+
+      expect(token).toBeString();
+      expect(token.length).toBeGreaterThan(0);
+
+      // Should be valid base64url (no +, /, or =)
+      expect(token).not.toContain("+");
+      expect(token).not.toContain("/");
+      expect(token).not.toContain("=");
+    });
+
+    it("includes machine identity in token", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.machineId).toBe(identity.id);
+      expect(token!.machineSigningKey).toBe(
+        Buffer.from(identity.signing.publicKey).toString("base64")
+      );
+      expect(token!.machineKeyExchangeKey).toBe(
+        Buffer.from(identity.keyExchange.publicKey).toString("base64")
+      );
+    });
+
+    it("includes relay URL in token", () => {
+      const identity = createMockIdentity();
+      const relayUrl = "wss://relay.example.com";
+      const encoded = createInviteToken(identity, relayUrl);
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.relayUrl).toBe(relayUrl);
+    });
+
+    it("uses default access type (session-invite)", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.accessType).toBe('session-invite');
+    });
+
+    it("accepts custom access type", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        accessType: 'full',
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.accessType).toBe('full');
+    });
+
+    it("accepts session ID for session-invite", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        accessType: 'session-invite',
+        sessionId: 'session-123',
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.accessType).toBe('session-invite');
+      expect(token!.sessionId).toBe('session-123');
+    });
+
+    it("sets expiry to 24 hours by default", () => {
+      const identity = createMockIdentity();
+      const before = Date.now() + 24 * 60 * 60 * 1000;
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const after = Date.now() + 24 * 60 * 60 * 1000;
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.expiresAt).toBeGreaterThanOrEqual(before);
+      expect(token!.expiresAt).toBeLessThanOrEqual(after);
+    });
+
+    it("accepts custom validity duration", () => {
+      const identity = createMockIdentity();
+      const oneHour = 60 * 60 * 1000;
+      const before = Date.now() + oneHour;
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        validityMs: oneHour,
+      });
+      const after = Date.now() + oneHour;
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.expiresAt).toBeGreaterThanOrEqual(before);
+      expect(token!.expiresAt).toBeLessThanOrEqual(after);
+    });
+
+    it("sets singleUse to false by default", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.singleUse).toBe(false);
+    });
+
+    it("accepts singleUse option", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        singleUse: true,
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.singleUse).toBe(true);
+    });
+
+    it("creates valid signature", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.signature).toBeString();
+      expect(token!.signature.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("parseInviteToken", () => {
+    it("parses valid token", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.version).toBe(1);
+      expect(token!.machineId).toBe(identity.id);
+    });
+
+    it("returns null for invalid base64", () => {
+      const token = parseInviteToken("not-valid-base64!!!");
+      expect(token).toBeNull();
+    });
+
+    it("returns null for invalid JSON", () => {
+      const invalidJson = Buffer.from("not json").toString("base64url");
+      const token = parseInviteToken(invalidJson);
+      expect(token).toBeNull();
+    });
+
+    it("returns null for missing fields", () => {
+      const incomplete = {
+        version: 1,
+        machineId: "test",
+        // Missing other required fields
+      };
+      const encoded = Buffer.from(JSON.stringify(incomplete)).toString(
+        "base64url"
+      );
+      const token = parseInviteToken(encoded);
+      expect(token).toBeNull();
+    });
+
+    it("returns null for invalid signature", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+
+      // Decode and tamper with signature
+      const tokenJson = Buffer.from(encoded, "base64url").toString("utf-8");
+      const token = JSON.parse(tokenJson);
+      token.signature = "invalid-signature";
+      const tamperedEncoded = Buffer.from(JSON.stringify(token)).toString(
+        "base64url"
+      );
+
+      const parsed = parseInviteToken(tamperedEncoded);
+      expect(parsed).toBeNull();
+    });
+
+    it("returns null if payload was modified", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+
+      // Decode and tamper with payload (keep signature)
+      const tokenJson = Buffer.from(encoded, "base64url").toString("utf-8");
+      const token = JSON.parse(tokenJson);
+      token.relayUrl = "wss://evil.example.com"; // Change payload
+      const tamperedEncoded = Buffer.from(JSON.stringify(token)).toString(
+        "base64url"
+      );
+
+      const parsed = parseInviteToken(tamperedEncoded);
+      expect(parsed).toBeNull();
+    });
+
+    it("verifies signature with correct public key", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+
+      // Should succeed - signature is valid
+      const token = parseInviteToken(encoded);
+      expect(token).not.toBeNull();
+    });
+
+    it("rejects token signed with different key", () => {
+      const identity1 = createMockIdentity("machine1");
+      const identity2 = createMockIdentity("machine2");
+
+      // Create token with identity1
+      const encoded = createInviteToken(identity1, "wss://relay.example.com");
+
+      // Decode and replace public key with identity2's key
+      const tokenJson = Buffer.from(encoded, "base64url").toString("utf-8");
+      const token = JSON.parse(tokenJson);
+      token.machineSigningKey = Buffer.from(
+        identity2.signing.publicKey
+      ).toString("base64");
+      const tamperedEncoded = Buffer.from(JSON.stringify(token)).toString(
+        "base64url"
+      );
+
+      // Should fail - signature doesn't match new public key
+      const parsed = parseInviteToken(tamperedEncoded);
+      expect(parsed).toBeNull();
+    });
+  });
+
+  describe("getPublicIdentityFromInvite", () => {
+    it("extracts public identity from token", () => {
+      const identity = createMockIdentity("my-machine");
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+
+      const publicIdentity = getPublicIdentityFromInvite(token!);
+
+      expect(publicIdentity.id).toBe(identity.id);
+      expect(publicIdentity.signingPublicKey).toBe(
+        Buffer.from(identity.signing.publicKey).toString("base64")
+      );
+      expect(publicIdentity.keyExchangePublicKey).toBe(
+        Buffer.from(identity.keyExchange.publicKey).toString("base64")
+      );
+      expect(publicIdentity.label).toBeUndefined();
+    });
+
+    it("omits label (not included in invite tokens)", () => {
+      const identity = createMockIdentity("my-machine");
+      const encoded = createInviteToken(identity, "wss://relay.example.com");
+      const token = parseInviteToken(encoded);
+
+      const publicIdentity = getPublicIdentityFromInvite(token!);
+
+      expect(publicIdentity.label).toBeUndefined();
+    });
+  });
+
+  describe("isInviteExpired", () => {
+    it("returns false for valid token", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        validityMs: 60 * 60 * 1000, // 1 hour
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(isInviteExpired(token!)).toBe(false);
+    });
+
+    it("returns true for expired token", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        validityMs: -1000, // Expired 1 second ago
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(isInviteExpired(token!)).toBe(true);
+    });
+
+    it("returns true for token expiring at current time", () => {
+      const identity = createMockIdentity();
+      const encoded = createInviteToken(identity, "wss://relay.example.com", {
+        validityMs: 0, // Expires now
+      });
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      // Might be flaky, but should generally be true
+      expect(isInviteExpired(token!)).toBe(true);
+    });
+  });
+
+  describe("integration", () => {
+    it("roundtrips token creation and parsing", () => {
+      const identity = createMockIdentity("test-machine");
+      const relayUrl = "wss://relay.example.com";
+      const options = {
+        accessType: 'full' as const,
+        validityMs: 3600000, // 1 hour
+        singleUse: true,
+      };
+
+      const encoded = createInviteToken(identity, relayUrl, options);
+      const token = parseInviteToken(encoded);
+
+      expect(token).not.toBeNull();
+      expect(token!.version).toBe(1);
+      expect(token!.machineId).toBe(identity.id);
+      expect(token!.relayUrl).toBe(relayUrl);
+      expect(token!.accessType).toBe('full');
+      expect(token!.singleUse).toBe(true);
+      expect(isInviteExpired(token!)).toBe(false);
+
+      const publicIdentity = getPublicIdentityFromInvite(token!);
+      expect(publicIdentity.id).toBe(identity.id);
+    });
+
+    it("creates URL-safe tokens", () => {
+      const identity = createMockIdentity();
+      const token = createInviteToken(identity, "wss://relay.example.com");
+
+      // Should be safe to use in URLs
+      const url = `https://app.example.com/join?token=${token}`;
+      const parsed = new URL(url);
+      expect(parsed.searchParams.get("token")).toBe(token);
+    });
+  });
+});

package/src/lib/tmux-lite/crypto/invites.ts

@@ -0,0 +1,215 @@
+/**
+ * Invite token creation and verification
+ *
+ * Invite tokens are signed JSON tokens that allow sharing access to a machine.
+ * They are base64url encoded for URL-safe transport.
+ *
+ * Token flow:
+ * 1. Create token payload (without signature)
+ * 2. Sign JSON-stringified payload with machine's signing key
+ * 3. Add signature to token
+ * 4. Base64url encode the full token JSON
+ */
+
+import type {
+  Identity,
+  InviteToken,
+  CreateInviteOptions,
+  AccessType,
+  PublicIdentity,
+} from "../../../types/identity.js";
+import { sign, verify } from "./identity.js";
+
+/** Default invite validity: 24 hours */
+const DEFAULT_VALIDITY_MS = 24 * 60 * 60 * 1000;
+
+/** Default access type for invites: session-invite (view-only) */
+const DEFAULT_ACCESS_TYPE: AccessType = 'session-invite';
+
+/**
+ * Create a signed invite token for sharing machine access
+ *
+ * The token contains:
+ * - Machine's public identity (signing and key exchange keys)
+ * - Relay URL to connect
+ * - Access type being granted
+ * - Expiry timestamp
+ * - Signature over the token data
+ *
+ * @param machineIdentity - The machine's complete identity (needs secret key for signing)
+ * @param relayUrl - The relay server URL to connect to
+ * @param options - Optional configuration (accessType, sessionId, validity, single-use)
+ * @returns Base64url-encoded signed token
+ *
+ * @example
+ * ```typescript
+ * const token = createInviteToken(
+ *   machineIdentity,
+ *   'wss://relay.example.com',
+ *   {
+ *     accessType: 'session-invite',
+ *     sessionId: 'session-123',
+ *     validityMs: 3600000, // 1 hour
+ *     singleUse: true
+ *   }
+ * );
+ * // Share token via URL: https://app.example.com/join?token=...
+ * ```
+ */
+export function createInviteToken(
+  machineIdentity: Identity,
+  relayUrl: string,
+  options?: CreateInviteOptions
+): string {
+  const validityMs = options?.validityMs ?? DEFAULT_VALIDITY_MS;
+  const accessType = options?.accessType ?? DEFAULT_ACCESS_TYPE;
+  const sessionId = options?.sessionId;
+  const singleUse = options?.singleUse ?? false;
+
+  // Create unsigned token payload
+  const unsignedToken: Omit<InviteToken, "signature"> = {
+    version: 1,
+    machineId: machineIdentity.id,
+    machineSigningKey: Buffer.from(
+      machineIdentity.signing.publicKey
+    ).toString("base64"),
+    machineKeyExchangeKey: Buffer.from(
+      machineIdentity.keyExchange.publicKey
+    ).toString("base64"),
+    relayUrl,
+    accessType,
+    sessionId,
+    expiresAt: Date.now() + validityMs,
+    singleUse,
+  };
+
+  // Sign the JSON-stringified payload
+  const payloadString = JSON.stringify(unsignedToken);
+  const payloadBytes = new TextEncoder().encode(payloadString);
+  const signatureBytes = sign(payloadBytes, machineIdentity.signing.secretKey);
+  const signature = Buffer.from(signatureBytes).toString("base64");
+
+  // Add signature to create complete token
+  const signedToken: InviteToken = {
+    ...unsignedToken,
+    signature,
+  };
+
+  // Encode as base64url for URL-safe transport
+  const tokenJson = JSON.stringify(signedToken);
+  return Buffer.from(tokenJson).toString("base64url");
+}
+
+/**
+ * Parse and verify a base64url-encoded invite token
+ *
+ * This function:
+ * 1. Decodes the base64url token
+ * 2. Parses the JSON
+ * 3. Validates the structure
+ * 4. Verifies the signature
+ *
+ * @param encodedToken - Base64url-encoded token string
+ * @returns Parsed token if valid, null if invalid or signature verification fails
+ *
+ * @example
+ * ```typescript
+ * const token = parseInviteToken(encodedToken);
+ * if (!token) {
+ *   console.error('Invalid token');
+ *   return;
+ * }
+ * if (isInviteExpired(token)) {
+ *   console.error('Token has expired');
+ *   return;
+ * }
+ * // Token is valid, use it to connect
+ * ```
+ */
+export function parseInviteToken(encodedToken: string): InviteToken | null {
+  try {
+    // Decode base64url
+    const tokenJson = Buffer.from(encodedToken, "base64url").toString("utf-8");
+    const token = JSON.parse(tokenJson) as InviteToken;
+
+    // Validate structure
+    if (
+      token.version !== 1 ||
+      !token.machineId ||
+      !token.machineSigningKey ||
+      !token.machineKeyExchangeKey ||
+      !token.relayUrl ||
+      !token.accessType ||
+      !token.expiresAt ||
+      typeof token.singleUse !== "boolean" ||
+      !token.signature
+    ) {
+      return null;
+    }
+
+    // Extract signature and recreate unsigned payload
+    const { signature, ...unsignedToken } = token;
+    const payloadString = JSON.stringify(unsignedToken);
+    const payloadBytes = new TextEncoder().encode(payloadString);
+
+    // Verify signature with machine's public signing key
+    const publicKey = new Uint8Array(
+      Buffer.from(token.machineSigningKey, "base64")
+    );
+    const signatureBytes = new Uint8Array(Buffer.from(signature, "base64"));
+    const isValid = verify(payloadBytes, signatureBytes, publicKey);
+
+    if (!isValid) {
+      return null;
+    }
+
+    return token;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract public identity information from an invite token
+ *
+ * This creates a PublicIdentity object that can be added to an access list.
+ *
+ * @param token - Parsed invite token
+ * @returns Public identity of the machine that created the token
+ *
+ * @example
+ * ```typescript
+ * const token = parseInviteToken(encodedToken);
+ * if (token) {
+ *   const machineIdentity = getPublicIdentityFromInvite(token);
+ *   // Add to access list, display in UI, etc.
+ * }
+ * ```
+ */
+export function getPublicIdentityFromInvite(token: InviteToken): PublicIdentity {
+  return {
+    id: token.machineId,
+    signingPublicKey: token.machineSigningKey,
+    keyExchangePublicKey: token.machineKeyExchangeKey,
+    label: undefined, // Invite tokens don't include labels
+  };
+}
+
+/**
+ * Check if an invite token has expired
+ *
+ * @param token - Parsed invite token
+ * @returns True if the current time is past the token's expiry
+ *
+ * @example
+ * ```typescript
+ * const token = parseInviteToken(encodedToken);
+ * if (token && isInviteExpired(token)) {
+ *   console.error('This invite has expired');
+ *   return;
+ * }
+ * ```
+ */
+export function isInviteExpired(token: InviteToken): boolean {
+  return Date.now() > token.expiresAt;
+}