Reorganize repo structure and standards references
This commit is contained in:
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;
|
||||
}
|
||||
+125
@@ -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;
|
||||
}
|
||||
Reference in new issue
Block a user