Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,84 @@
import { describe, expect, it } from "vitest";
import jwt from "jsonwebtoken";
import { parseDocumentName, verifyCollabToken } from "./auth.js";
const SECRET = "test-secret-please-rotate-in-prod-min-32-bytes";
function signToken(claims: Record<string, unknown>, expiresInSeconds = 60): string {
return jwt.sign(claims, SECRET, { algorithm: "HS256", expiresIn: expiresInSeconds });
}
describe("parseDocumentName", () => {
it("splits a well-formed name into three parts", () => {
expect(parseDocumentName("tenant_abc:kb-article:art_123")).toEqual({
tenantId: "tenant_abc",
resourceType: "kb-article",
resourceId: "art_123",
});
});
it("preserves colons inside the resourceId", () => {
expect(parseDocumentName("t:kb:foo:bar:baz")).toEqual({
tenantId: "t",
resourceType: "kb",
resourceId: "foo:bar:baz",
});
});
it("returns null for malformed names", () => {
expect(parseDocumentName("")).toBeNull();
expect(parseDocumentName("tenant_only")).toBeNull();
expect(parseDocumentName("tenant:type")).toBeNull();
expect(parseDocumentName(":kb:art")).toBeNull();
});
});
describe("verifyCollabToken", () => {
const docName = "tenant_abc:kb-article:art_123";
it("accepts a valid token whose claims match the document name", () => {
const token = signToken({ userId: "user_1", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" });
const ctx = verifyCollabToken(token, docName, { secret: SECRET });
expect(ctx).toEqual({ userId: "user_1", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" });
});
it("accepts `sub` as a userId fallback", () => {
const token = signToken({ sub: "user_2", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" });
expect(verifyCollabToken(token, docName, { secret: SECRET })?.userId).toBe("user_2");
});
it("refuses tokens signed with a different secret", () => {
const token = jwt.sign({ userId: "u", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" }, "other-secret", { algorithm: "HS256" });
expect(verifyCollabToken(token, docName, { secret: SECRET })).toBeNull();
});
it("refuses expired tokens", () => {
const token = signToken({ userId: "u", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" }, -120);
expect(verifyCollabToken(token, docName, { secret: SECRET, clockTolerance: 0 })).toBeNull();
});
it("refuses cross-tenant token reuse", () => {
const token = signToken({ userId: "u", tenantId: "OTHER", resourceType: "kb-article", resourceId: "art_123" });
expect(verifyCollabToken(token, docName, { secret: SECRET })).toBeNull();
});
it("refuses token whose resourceType differs from the document", () => {
const token = signToken({ userId: "u", tenantId: "tenant_abc", resourceType: "crm-note", resourceId: "art_123" });
expect(verifyCollabToken(token, docName, { secret: SECRET })).toBeNull();
});
it("refuses token whose resourceId differs from the document", () => {
const token = signToken({ userId: "u", tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "other" });
expect(verifyCollabToken(token, docName, { secret: SECRET })).toBeNull();
});
it("refuses tokens with no userId / sub claim", () => {
const token = signToken({ tenantId: "tenant_abc", resourceType: "kb-article", resourceId: "art_123" });
expect(verifyCollabToken(token, docName, { secret: SECRET })).toBeNull();
});
it("refuses missing or empty token", () => {
expect(verifyCollabToken("", docName, { secret: SECRET })).toBeNull();
});
});
@@ -0,0 +1,119 @@
/**
* Hocuspocus authentication hook.
*
* Verifies a short-lived JWT issued by the web app's collab-token endpoint.
* Claims:
* { sub: userId, tenantId, resourceType, resourceId, exp }
*
* Refuses the connection (Hocuspocus closes the WebSocket with a 403-style
* close-code) when:
* - HOCUSPOCUS_AUTH_SECRET is unset on the server side
* - the JWT is missing, malformed, expired, or signed with the wrong secret
* - the JWT's tenantId / resourceType / resourceId do not match the
* documentName (`${tenantId}:${resourceType}:${resourceId}`) the client
* is requesting — defence-in-depth against cross-tenant doc access.
*
* Returns a context object stored on the Hocuspocus connection: persistence
* + permission-revoke handlers downstream pull tenantId from this context.
*
* Refs: docs/improvement-plan/05-business-features/realtime-collab.md
*/
import { Extension, onAuthenticatePayload } from "@hocuspocus/server";
import jwt from "jsonwebtoken";
export type HocuspocusConnectionContext = {
readonly userId: string;
readonly tenantId: string;
readonly resourceType: string;
readonly resourceId: string;
};
export type AuthExtensionOptions = {
readonly secret: string;
/** Optional clock-skew tolerance in seconds; defaults to 30s. */
readonly clockTolerance?: number;
};
/**
* Parse `tenantId:resourceType:resourceId` document-name into its parts.
* Returns `null` for malformed names — caller refuses the connection.
*/
export function parseDocumentName(documentName: string): {
tenantId: string;
resourceType: string;
resourceId: string;
} | null {
if (typeof documentName !== "string" || documentName.length === 0) return null;
// resourceId may itself contain `:` (e.g. namespaced slugs); split into 3 parts only.
const parts = documentName.split(":");
if (parts.length < 3) return null;
const [tenantId, resourceType, ...rest] = parts;
const resourceId = rest.join(":");
if (!tenantId || !resourceType || !resourceId) return null;
return { tenantId, resourceType, resourceId };
}
type TokenClaims = {
sub?: string;
userId?: string;
tenantId?: string;
resourceType?: string;
resourceId?: string;
};
/**
* Verify the JWT + check claim/document name parity. Returns the connection
* context on success or `null` on any failure (caller throws to refuse).
*/
export function verifyCollabToken(
token: string,
documentName: string,
options: AuthExtensionOptions,
): HocuspocusConnectionContext | null {
if (!token) return null;
const parsed = parseDocumentName(documentName);
if (!parsed) return null;
let claims: TokenClaims;
try {
claims = jwt.verify(token, options.secret, {
algorithms: ["HS256"],
clockTolerance: options.clockTolerance ?? 30,
}) as TokenClaims;
} catch {
return null;
}
const userId = claims.userId ?? claims.sub;
if (!userId || typeof userId !== "string") return null;
if (claims.tenantId !== parsed.tenantId) return null;
if (claims.resourceType !== parsed.resourceType) return null;
if (claims.resourceId !== parsed.resourceId) return null;
return {
userId,
tenantId: parsed.tenantId,
resourceType: parsed.resourceType,
resourceId: parsed.resourceId,
};
}
/**
* Hocuspocus extension hook. Wired in `apps/hocuspocus/src/index.ts`.
*
* When `secret` is empty/null, the extension refuses every connection — this
* is the safe default if HOCUSPOCUS_AUTH_SECRET is unset on the server side
* (mis-configured prod deploy should not silently fall through to anonymous
* collaboration).
*/
export function createAuthExtension(options: AuthExtensionOptions): Extension {
return {
async onAuthenticate(data: onAuthenticatePayload) {
const context = verifyCollabToken(data.token, data.documentName, options);
if (!context) {
throw new Error("hocuspocus: authentication refused");
}
return context satisfies HocuspocusConnectionContext;
},
} as Extension;
}
@@ -0,0 +1,125 @@
import { describe, expect, it, vi } from "vitest";
import { fetchCollabDoc, storeCollabDoc, type DatabaseExtensionDeps } from "./database.js";
type StubCollabRow = {
tenantId: string;
resourceType: string;
resourceId: string;
ydocState: Buffer;
version: number;
lastUpdatedAt: Date;
};
function createStubDb() {
const rows = new Map<string, StubCollabRow>();
const findUnique = vi.fn(async ({ where }: { where: { tenantId_resourceType_resourceId: { tenantId: string; resourceType: string; resourceId: string } }; select?: unknown }) => {
const { tenantId, resourceType, resourceId } = where.tenantId_resourceType_resourceId;
const key = `${tenantId}:${resourceType}:${resourceId}`;
const row = rows.get(key);
return row ? { ydocState: row.ydocState } : null;
});
type UpsertArgs = {
where: { tenantId_resourceType_resourceId: { tenantId: string; resourceType: string; resourceId: string } };
create: StubCollabRow;
update: { ydocState: Buffer; version: { increment: number }; lastUpdatedAt: Date };
};
const upsert = vi.fn(async ({ where, create, update }: UpsertArgs) => {
const { tenantId, resourceType, resourceId } = where.tenantId_resourceType_resourceId;
const key = `${tenantId}:${resourceType}:${resourceId}`;
const existing = rows.get(key);
if (existing) {
existing.ydocState = update.ydocState;
existing.version += update.version.increment;
existing.lastUpdatedAt = update.lastUpdatedAt;
return existing;
}
rows.set(key, { ...create });
return create;
});
return {
db: { collabDoc: { findUnique, upsert } },
rows,
};
}
function buildDeps(): { deps: DatabaseExtensionDeps; rows: Map<string, StubCollabRow> } {
const stub = createStubDb();
return {
rows: stub.rows,
deps: {
db: stub.db as unknown as DatabaseExtensionDeps["db"],
maxPayloadBytes: 1024,
clock: () => new Date("2026-05-17T12:00:00Z"),
},
};
}
describe("fetchCollabDoc", () => {
it("returns null when no row exists for the document", async () => {
const { deps } = buildDeps();
const result = await fetchCollabDoc("t:kb-article:art_1", deps);
expect(result).toBeNull();
});
it("returns null for malformed document names", async () => {
const { deps } = buildDeps();
expect(await fetchCollabDoc("malformed", deps)).toBeNull();
});
it("returns a Uint8Array when the row exists", async () => {
const { deps, rows } = buildDeps();
rows.set("t:kb-article:art_1", {
tenantId: "t",
resourceType: "kb-article",
resourceId: "art_1",
ydocState: Buffer.from([1, 2, 3, 4]),
version: 7,
lastUpdatedAt: new Date(),
});
const result = await fetchCollabDoc("t:kb-article:art_1", deps);
expect(result).toBeInstanceOf(Uint8Array);
expect(Array.from(result ?? [])).toEqual([1, 2, 3, 4]);
});
});
describe("storeCollabDoc", () => {
it("inserts a new row on first store", async () => {
const { deps, rows } = buildDeps();
await storeCollabDoc("t:kb-article:art_1", new Uint8Array([9, 9, 9]), deps);
const row = rows.get("t:kb-article:art_1");
expect(row).toBeDefined();
expect(row?.version).toBe(1);
expect(Array.from(row?.ydocState ?? new Uint8Array())).toEqual([9, 9, 9]);
});
it("increments version on subsequent stores", async () => {
const { deps, rows } = buildDeps();
await storeCollabDoc("t:kb-article:art_1", new Uint8Array([1]), deps);
await storeCollabDoc("t:kb-article:art_1", new Uint8Array([2]), deps);
await storeCollabDoc("t:kb-article:art_1", new Uint8Array([3]), deps);
expect(rows.get("t:kb-article:art_1")?.version).toBe(3);
expect(Array.from(rows.get("t:kb-article:art_1")?.ydocState ?? new Uint8Array())).toEqual([3]);
});
it("refuses payloads exceeding maxPayloadBytes", async () => {
const { deps } = buildDeps();
const large = new Uint8Array(2048);
await expect(storeCollabDoc("t:kb:art_1", large, deps)).rejects.toThrow(/exceeds HOCUSPOCUS_MAX_PAYLOAD_BYTES/);
});
it("is a no-op for malformed document names", async () => {
const { deps, rows } = buildDeps();
await storeCollabDoc("malformed", new Uint8Array([1]), deps);
expect(rows.size).toBe(0);
});
it("isolates tenants — same resourceType/Id under different tenant gets its own row", async () => {
const { deps, rows } = buildDeps();
await storeCollabDoc("tenant_a:kb:art_1", new Uint8Array([1]), deps);
await storeCollabDoc("tenant_b:kb:art_1", new Uint8Array([2]), deps);
expect(rows.size).toBe(2);
expect(Array.from(rows.get("tenant_a:kb:art_1")?.ydocState ?? new Uint8Array())).toEqual([1]);
expect(Array.from(rows.get("tenant_b:kb:art_1")?.ydocState ?? new Uint8Array())).toEqual([2]);
});
});
@@ -0,0 +1,103 @@
/**
* Hocuspocus database extension persisting Y.js docs to Postgres
* (`CollabDoc` table).
*
* `fetch({ documentName })` → Loads BLOB from Postgres on connect; returns
* `null` when no row exists (Hocuspocus then
* initialises a fresh in-memory Y.Doc).
* `store({ documentName, state })` → Upserts the BLOB, bumps `version`,
* refreshes `lastUpdatedAt`. Debounced by
* Hocuspocus per the server-level
* `debounce` / `maxDebounce` settings.
*
* The DocumentName is parsed via `parseDocumentName()` (see auth.ts) and is
* authoritative for the `(tenantId, resourceType, resourceId)` triple. Auth
* has already verified that the connection has access to this triple; here
* we just persist the bytes.
*
* Refs: docs/improvement-plan/05-business-features/realtime-collab.md
*/
import { Database } from "@hocuspocus/extension-database";
import type { Extension } from "@hocuspocus/server";
import type { DbClient } from "@toolctrl/db/client.server";
import { parseDocumentName } from "./auth.js";
export type DatabaseExtensionDeps = {
/** Prisma client (write-able). */
readonly db: Pick<DbClient, "collabDoc">;
/** Maximum bytes we will store per doc — protects from runaway state-bloat. */
readonly maxPayloadBytes: number;
/**
* Optional clock hook for deterministic tests. Defaults to `() => new Date()`.
*/
readonly clock?: () => Date;
};
/**
* Internal `fetch` implementation — exported for unit-testing.
*/
export async function fetchCollabDoc(documentName: string, deps: DatabaseExtensionDeps): Promise<Uint8Array | null> {
const parsed = parseDocumentName(documentName);
if (!parsed) return null;
const row = await deps.db.collabDoc.findUnique({
where: {
tenantId_resourceType_resourceId: {
tenantId: parsed.tenantId,
resourceType: parsed.resourceType,
resourceId: parsed.resourceId,
},
},
select: { ydocState: true },
});
if (!row) return null;
// Prisma returns `Buffer` for Bytes columns — wrap to Uint8Array for Y.js.
return new Uint8Array(row.ydocState);
}
/**
* Internal `store` implementation — exported for unit-testing.
*/
export async function storeCollabDoc(documentName: string, state: Uint8Array, deps: DatabaseExtensionDeps): Promise<void> {
const parsed = parseDocumentName(documentName);
if (!parsed) return;
if (state.byteLength > deps.maxPayloadBytes) {
throw new Error(
`hocuspocus: refusing to persist Y.js state of ${state.byteLength} bytes — exceeds HOCUSPOCUS_MAX_PAYLOAD_BYTES=${deps.maxPayloadBytes}`,
);
}
const now = (deps.clock ?? (() => new Date()))();
const buffer = Buffer.from(state);
await deps.db.collabDoc.upsert({
where: {
tenantId_resourceType_resourceId: {
tenantId: parsed.tenantId,
resourceType: parsed.resourceType,
resourceId: parsed.resourceId,
},
},
create: {
tenantId: parsed.tenantId,
resourceType: parsed.resourceType,
resourceId: parsed.resourceId,
ydocState: buffer,
version: 1,
lastUpdatedAt: now,
},
update: {
ydocState: buffer,
version: { increment: 1 },
lastUpdatedAt: now,
},
});
}
/**
* Build the Hocuspocus database extension wired to the Prisma client.
*/
export function createDatabaseExtension(deps: DatabaseExtensionDeps): Extension {
return new Database({
fetch: async ({ documentName }) => fetchCollabDoc(documentName, deps),
store: async ({ documentName, state }) => storeCollabDoc(documentName, state, deps),
}) as unknown as Extension;
}