feat: expose core identity transport

packages/contracts/tests/identity.test.ts

@@ -3,6 +3,7 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
+  type EkklesiaUserId,
   isAnonymousPrincipal,
   isAuthenticatedPrincipal,
   parseEkklesiaUserId,
@@ -14,6 +15,25 @@ describe("Ekklesia identity contracts", () => {
     expect(parseEkklesiaUserId("user_123")).toBe("user_123");
   });
 
+  it("is opaque at the type level: a plain string is not assignable without parsing", () => {
+    // @ts-expect-error a bare string must not satisfy the branded EkklesiaUserId type.
+    const notAllowed: EkklesiaUserId = "raw-string";
+    expect(notAllowed).toBe("raw-string"); // the brand adds no runtime wrapper or tag
+  });
+
+  it("serializes as a plain opaque string despite the type-level brand", () => {
+    const userId = parseEkklesiaUserId("user_123");
+
+    expect(JSON.stringify({ userId })).toBe('{"userId":"user_123"}');
+    expect(`${userId}`).toBe("user_123");
+    expect(typeof userId).toBe("string");
+  });
+
+  it("does not assume any particular id format such as UUID", () => {
+    expect(() => parseEkklesiaUserId("not-a-uuid-at-all")).not.toThrow();
+    expect(() => parseEkklesiaUserId("2aKp4jPeV1QbXwyz1OH6IcAUfl2n1fc1")).not.toThrow();
+  });
+
   it("rejects an empty or oversized user id", () => {
     expect(() => parseEkklesiaUserId("")).toThrow();
     expect(() => parseEkklesiaUserId("   ")).toThrow();