@hearthlog/ledger 0.0.0-stage → 0.1.0

package/src/auth.ts

@@ -0,0 +1,186 @@
+import {
+    type AccessClaims,
+    parseAccessClaims,
+} from "./contracts";
+
+const ACCESS_PREFIX = "ledger_v1";
+
+export const SOCKET_PROTOCOL = "ledger.v1";
+
+export function bearerToken(request: Request): string {
+    const value = request.headers.get("authorization");
+    if (!value?.startsWith("Bearer ") || value.length === "Bearer ".length) {
+        throw new Error("missing bearer token");
+    }
+    return value.slice("Bearer ".length);
+}
+
+export async function authorizeAdmin(
+    request: Request,
+    env: Env,
+): Promise<void> {
+    const supplied = bearerToken(request);
+    if (!(await constantTimeStrings(supplied, env.ADMIN_TOKEN))) {
+        throw new Error("invalid administrator token");
+    }
+}
+
+export async function issueAccess(
+    env: Env,
+    appId: string,
+    principalId: string,
+    generation: number,
+): Promise<string> {
+    const claims: AccessClaims = {
+        version: 1,
+        kind: "access",
+        appId,
+        principalId,
+        generation,
+        keyId: currentKeyId(env),
+    };
+    return sign(env, ACCESS_PREFIX, claims);
+}
+
+export async function verifyAccess(
+    env: Env,
+    token: string,
+): Promise<AccessClaims> {
+    return parseAccessClaims(await verify(env, ACCESS_PREFIX, token));
+}
+
+export function requestOrigin(request: Request): string | null {
+    return request.headers.get("origin");
+}
+
+export function originAllowed(env: Env, origin: string | null): boolean {
+    if (origin === null) return true;
+    return env.ALLOWED_ORIGINS.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .includes(origin);
+}
+
+export async function constantTimeStrings(
+    left: string,
+    right: string,
+): Promise<boolean> {
+    const encoder = new TextEncoder();
+    const [leftHash, rightHash] = await Promise.all([
+        crypto.subtle.digest("SHA-256", encoder.encode(left)),
+        crypto.subtle.digest("SHA-256", encoder.encode(right)),
+    ]);
+    return crypto.subtle.timingSafeEqual(leftHash, rightHash);
+}
+
+async function sign(
+    env: Env,
+    prefix: string,
+    claims: AccessClaims,
+): Promise<string> {
+    const payload = encodeBase64Url(
+        new TextEncoder().encode(JSON.stringify(claims)),
+    );
+    const message = `${prefix}.${payload}`;
+    const signature = await hmac(currentKey(env), message);
+    return `${message}.${encodeBase64Url(signature)}`;
+}
+
+async function verify(
+    env: Env,
+    prefix: string,
+    token: string,
+): Promise<unknown> {
+    const parts = token.split(".");
+    if (
+        parts.length !== 3 ||
+        parts[0] !== prefix ||
+        !parts[1] ||
+        !parts[2]
+    ) {
+        throw new Error("invalid signed token");
+    }
+
+    const payloadBytes = decodeBase64Url(parts[1]);
+    const value: unknown = JSON.parse(new TextDecoder().decode(payloadBytes));
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("invalid token payload");
+    }
+    const keyId = (value as Record<string, unknown>).keyId;
+    if (typeof keyId !== "string") throw new Error("missing token key id");
+
+    const expected = await hmac(verificationKey(env, keyId), `${prefix}.${parts[1]}`);
+    const supplied = decodeBase64Url(parts[2]);
+    if (
+        supplied.byteLength !== expected.byteLength ||
+        !crypto.subtle.timingSafeEqual(supplied, expected)
+    ) {
+        throw new Error("invalid token signature");
+    }
+    return value;
+}
+
+async function hmac(key: string, message: string): Promise<Uint8Array> {
+    const encoder = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey(
+        "raw",
+        encoder.encode(key),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+    );
+    return new Uint8Array(
+        await crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(message)),
+    );
+}
+
+function currentKey(env: Env): string {
+    if (new TextEncoder().encode(env.TOKEN_SIGNING_KEY_CURRENT).byteLength < 32) {
+        throw new Error(
+            "TOKEN_SIGNING_KEY_CURRENT must contain at least 32 bytes",
+        );
+    }
+    return env.TOKEN_SIGNING_KEY_CURRENT;
+}
+
+function currentKeyId(env: Env): string {
+    const keyId = env.TOKEN_SIGNING_KEY_ID.trim();
+    if (!keyId) throw new Error("TOKEN_SIGNING_KEY_ID is empty");
+    return keyId;
+}
+
+function verificationKey(env: Env, keyId: string): string {
+    if (keyId === currentKeyId(env)) return currentKey(env);
+    if (
+        env.TOKEN_SIGNING_PREVIOUS_KEY_ID &&
+        keyId === env.TOKEN_SIGNING_PREVIOUS_KEY_ID &&
+        env.TOKEN_SIGNING_KEY_PREVIOUS
+    ) {
+        return env.TOKEN_SIGNING_KEY_PREVIOUS;
+    }
+    throw new Error("unknown signing key id");
+}
+
+function encodeBase64Url(bytes: Uint8Array): string {
+    let binary = "";
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
+}
+
+function decodeBase64Url(value: string): Uint8Array {
+    try {
+        const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+        const padded = normalized.padEnd(
+            normalized.length + ((4 - (normalized.length % 4)) % 4),
+            "=",
+        );
+        return Uint8Array.from(atob(padded), (character) =>
+            character.charCodeAt(0),
+        );
+    } catch {
+        throw new Error("invalid base64url value");
+    }
+}

package/src/contracts.ts

@@ -0,0 +1,251 @@
+import { Value } from "@sinclair/typebox/value";
+import type { Static, TSchema } from "@sinclair/typebox";
+
+import { validationError } from "./errors";
+import {
+    apiModels,
+    type AppendEventsResponse,
+    type StoredEvent,
+} from "./schemas";
+
+export interface AccessClaims {
+    version: number;
+    kind: "access";
+    appId: string;
+    principalId: string;
+    generation: number;
+    keyId: string;
+}
+
+export const INTERNAL_SOCKET_ACCESS_HEADER = "x-ledger-internal-access";
+
+export interface SocketAttachment {
+    replayVersion?: number;
+    logId: string;
+    cursor: number;
+    principalId: string;
+    generation: number;
+    connectionId?: string;
+    connectedAt?: string;
+    lastSentAt?: string;
+    client?: {
+        userAgent: string | null;
+        ip: string | null;
+        country: string | null;
+        colo: string | null;
+    };
+}
+
+export type SocketFrame =
+    | { type: "event"; event: StoredEvent }
+    | { type: "ready"; headVersion: number }
+    | {
+          type: "resync_required";
+          headVersion: number;
+          reason: "gap_too_large" | "cursor_ahead";
+      }
+    | { type: "error"; code: string };
+
+export interface InitializeRequest {
+    appId: string;
+    name: string;
+    principalId: string;
+    generation: number;
+    createdAt: string;
+    /** The application's event policy, as JSON; absent for none. */
+    eventPolicy?: string;
+    /** The application is being filled by an identity-preserving import and serves nobody yet. */
+    importing?: boolean;
+}
+
+export interface RotateRequest {
+    principalId: string;
+    generation: number;
+    createdAt: string;
+}
+
+export interface RevokeRequest {
+    revokedAt: string;
+}
+
+const UUID_PATTERN =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function parseUuid(value: unknown, label: string): string {
+    if (typeof value !== "string" || !UUID_PATTERN.test(value)) {
+        throw validationError(`${label} must be a UUID`);
+    }
+    return value.toLowerCase();
+}
+
+export function parseNonnegativeInteger(value: unknown, label: string): number {
+    if (!Number.isSafeInteger(value) || (value as number) < 0) {
+        throw validationError(`${label} must be a non-negative safe integer`);
+    }
+    return value as number;
+}
+
+export function parsePositiveInteger(value: unknown, label: string): number {
+    const parsed = parseNonnegativeInteger(value, label);
+    if (parsed < 1) throw validationError(`${label} must be positive`);
+    return parsed;
+}
+
+export function parseIsoTimestamp(value: unknown, label: string): string {
+    if (
+        typeof value !== "string" ||
+        value.trim() === "" ||
+        !Number.isFinite(Date.parse(value))
+    ) {
+        throw validationError(`${label} must be an ISO-8601 timestamp`);
+    }
+    return value;
+}
+
+export function parseInitializeRequest(value: unknown): InitializeRequest {
+    const record = strictRecord(
+        value,
+        ["appId", "name", "principalId", "generation", "createdAt", "eventPolicy", "importing"],
+        "initialize request",
+    );
+    return {
+        ...(typeof record.eventPolicy === "string" ? { eventPolicy: record.eventPolicy } : {}),
+        ...(record.importing === true ? { importing: true } : {}),
+        appId: parseUuid(record.appId, "appId"),
+        name: requiredString(record.name, "name"),
+        principalId: parseUuid(record.principalId, "principalId"),
+        generation: parsePositiveInteger(record.generation, "generation"),
+        createdAt: parseIsoTimestamp(record.createdAt, "createdAt"),
+    };
+}
+
+export function parseRotateRequest(value: unknown): RotateRequest {
+    const record = strictRecord(
+        value,
+        ["principalId", "generation", "createdAt"],
+        "rotate request",
+    );
+    return {
+        principalId: parseUuid(record.principalId, "principalId"),
+        generation: parsePositiveInteger(record.generation, "generation"),
+        createdAt: parseIsoTimestamp(record.createdAt, "createdAt"),
+    };
+}
+
+export function parseRevokeRequest(value: unknown): RevokeRequest {
+    const record = strictRecord(value, ["revokedAt"], "revoke request");
+    return {
+        revokedAt: parseIsoTimestamp(record.revokedAt, "revokedAt"),
+    };
+}
+
+export function parseAccessClaims(value: unknown): AccessClaims {
+    const record = recordValue(value, "access token claims");
+    if (record.version !== 1 || record.kind !== "access") {
+        throw validationError("invalid access token claims");
+    }
+    return {
+        version: 1,
+        kind: "access",
+        appId: parseUuid(record.appId, "appId"),
+        principalId: parseUuid(record.principalId, "principalId"),
+        generation: parsePositiveInteger(record.generation, "generation"),
+        keyId: requiredString(record.keyId, "keyId"),
+    };
+}
+
+export function parseSocketAttachment(value: unknown): SocketAttachment {
+    const record = recordValue(value, "socket attachment");
+    return {
+        logId: parseUuid(record.logId, "logId"),
+        ...(record.replayVersion === undefined ? {} : { replayVersion: parseNonnegativeInteger(record.replayVersion, "replayVersion") }),
+        cursor: parseNonnegativeInteger(record.cursor, "cursor"),
+        principalId: parseUuid(record.principalId, "principalId"),
+        generation: parsePositiveInteger(record.generation, "generation"),
+        ...(record.connectionId === undefined
+            ? {}
+            : { connectionId: parseUuid(record.connectionId, "connectionId") }),
+        ...(record.connectedAt === undefined
+            ? {}
+            : {
+                  connectedAt: parseIsoTimestamp(
+                      record.connectedAt,
+                      "connectedAt",
+                  ),
+              }),
+        ...(record.lastSentAt === undefined
+            ? {}
+            : {
+                  lastSentAt: parseIsoTimestamp(
+                      record.lastSentAt,
+                      "lastSentAt",
+                  ),
+              }),
+        ...(record.client === undefined
+            ? {}
+            : { client: parseSocketClient(record.client) }),
+    };
+}
+
+function parseSocketClient(
+    value: unknown,
+): NonNullable<SocketAttachment["client"]> {
+    const record = recordValue(value, "socket client");
+    const field = (name: string, limit: number) =>
+        typeof record[name] === "string" ? record[name].slice(0, limit) : null;
+    return {
+        userAgent: field("userAgent", 512),
+        ip: field("ip", 64),
+        country: field("country", 16),
+        colo: field("colo", 16),
+    };
+}
+
+export function parseStoredAppendEventsResponse(
+    value: unknown,
+): AppendEventsResponse {
+    if (!Value.Check(apiModels.AppendEventsResponse, value)) {
+        throw new Error("invalid persisted idempotency response");
+    }
+    return value;
+}
+
+export function decodeRpc<T extends TSchema>(
+    schema: T,
+    value: unknown,
+    label: string,
+): Static<T> {
+    if (!Value.Check(schema, value)) {
+        throw validationError(`invalid ${label}`);
+    }
+    return value;
+}
+
+function strictRecord(
+    value: unknown,
+    fields: readonly string[],
+    label: string,
+): Record<string, unknown> {
+    const record = recordValue(value, label);
+    const allowed = new Set(fields);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw validationError(`${label} contains unknown field ${key}`);
+        }
+    }
+    return record;
+}
+
+function recordValue(value: unknown, label: string): Record<string, unknown> {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw validationError(`${label} must be a JSON object`);
+    }
+    return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, label: string): string {
+    if (typeof value !== "string") {
+        throw validationError(`${label} must be a string`);
+    }
+    return value;
+}

package/src/domain.ts

@@ -0,0 +1,245 @@
+import type {
+    AppendEventsRequest,
+    IncomingEvent,
+    StoredEvent,
+} from "./schemas";
+import {
+    invalidEvent,
+    LedgerError,
+    validationError,
+} from "./errors";
+import { parseUuid } from "./contracts";
+import { FILE_REFERENCES, type FileReference } from "#generated/event-schemas";
+
+/** The largest millisecond timestamp a JavaScript Date can represent. */
+const MAX_EVENT_TIMESTAMP = 8_640_000_000_000_000;
+
+export async function hashAppendRequest(
+    logId: string,
+    request: AppendEventsRequest,
+): Promise<string> {
+    const normalized = canonicalJson({
+        logId,
+        ...(request.actionId ? { actionId: request.actionId } : {}),
+        ...(request.expectedLogVersion !== undefined ? { expectedLogVersion: request.expectedLogVersion } : {}),
+        events: request.events.map((event) => ({
+            id: event.id ?? null,
+            type: event.type,
+            timestamp: event.timestamp ?? null,
+            entityId: event.entityId,
+            baseEntityVersion: event.baseEntityVersion ?? null,
+            payload: event.payload,
+        })),
+    });
+    const bytes = new TextEncoder().encode(normalized);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+
+export function validateIncomingEvents(
+    events: readonly IncomingEvent[],
+    references: Readonly<Record<string, FileReference>> = FILE_REFERENCES,
+): void {
+    const eventIds = new Set<string>();
+    for (const event of events) {
+        validateIncomingEvent(event, references);
+        if (!event.id) continue;
+        if (eventIds.has(event.id)) {
+            throw invalidEvent("event ids must be unique within a request");
+        }
+        eventIds.add(event.id);
+    }
+}
+
+export function validateIncomingEvent(
+    event: IncomingEvent,
+    references: Readonly<Record<string, FileReference>> = FILE_REFERENCES,
+): void {
+    if (event.type.trim() === "") {
+        throw invalidEvent("event type must not be empty");
+    }
+    if (event.entityId.trim() === "") {
+        throw invalidEvent("entityId must not be empty");
+    }
+    if (event.type === "EVENTS_EXCISED") {
+        validateExcisionPayload(event);
+    }
+    fileReference(event, references);
+}
+
+/**
+ * An accepted event that names an immutable file version grants its log that version. An add must
+ * name one; an update does so only when it replaces the file. The entity id must be `<entity>:<id>`.
+ * The references come from the installed modules' entity definitions (`fileReference`).
+ */
+export function fileReference(
+    event: IncomingEvent,
+    references: Readonly<Record<string, FileReference>> = FILE_REFERENCES,
+): { ownerId: string; fileVersionId: string } | null {
+    const reference = references[event.type];
+    if (!reference) return null;
+    if (!reference.requiredOnAdd && event.payload[reference.versionKey] === undefined) return null;
+    let ownerId: string;
+    let fileVersionId: string;
+    try {
+        ownerId = parseUuid(event.payload.id, `${reference.entity} id`);
+        fileVersionId = parseUuid(event.payload[reference.versionKey], `${reference.entity} file version id`);
+    } catch {
+        throw invalidEvent(`${reference.entity} file reference requires UUID id and ${reference.versionKey}`);
+    }
+    if (event.entityId !== `${reference.entity}:${ownerId}`) {
+        throw invalidEvent(`${reference.entity} entityId must match payload id`);
+    }
+    return { ownerId, fileVersionId };
+}
+
+const MAX_EXCISION_TARGETS = 200;
+
+function validateExcisionPayload(event: IncomingEvent): void {
+    const eventIds = event.payload.eventIds;
+    if (!Array.isArray(eventIds) || eventIds.length === 0) {
+        throw invalidEvent("excision requires eventIds");
+    }
+    if (eventIds.length > MAX_EXCISION_TARGETS) {
+        throw invalidEvent(`excision is limited to ${MAX_EXCISION_TARGETS} events`);
+    }
+    const unique = new Set<string>();
+    for (const target of eventIds) {
+        if (typeof target !== "string" || target.trim() === "") {
+            throw invalidEvent("excision targets must be non-empty event ids");
+        }
+        if (unique.has(target)) {
+            throw invalidEvent("excision targets must be unique");
+        }
+        unique.add(target);
+    }
+    if (event.id && unique.has(event.id)) {
+        throw invalidEvent("an excision cannot remove itself");
+    }
+}
+
+export function validateEntityChain(
+    entityId: string,
+    events: readonly IncomingEvent[],
+    currentEntityVersion: number | undefined,
+    currentLogVersion: number,
+): void {
+    if (events.length === 0) return;
+
+    if (currentEntityVersion !== undefined) {
+        events.forEach((event, offset) => {
+            const expected = currentEntityVersion + offset;
+            const actual = event.baseEntityVersion ?? undefined;
+            if (offset === 0 && actual !== expected) {
+                if (actual === undefined) {
+                    throw invalidEntityVersionChain(
+                        entityId,
+                        expected,
+                        undefined,
+                    );
+                }
+                throw new LedgerError(409, {
+                    code: "entity_conflict",
+                    entityId,
+                    currentEntityVersion,
+                    currentLogVersion,
+                });
+            }
+            if (offset > 0 && actual !== expected) {
+                throw invalidEntityVersionChain(
+                    entityId,
+                    expected,
+                    actual,
+                );
+            }
+        });
+        return;
+    }
+
+    events.forEach((event, offset) => {
+        const expected = offset > 0 ? offset : undefined;
+        const actual = event.baseEntityVersion ?? undefined;
+        if (actual !== expected) {
+            throw invalidEntityVersionChain(
+                entityId,
+                expected,
+                actual,
+            );
+        }
+    });
+}
+
+export function buildStoredEvent(
+    incoming: IncomingEvent,
+    version: number,
+    entityVersion: number,
+): StoredEvent {
+    const timestamp = incoming.timestamp ?? Date.now();
+    if (
+        !Number.isSafeInteger(timestamp) ||
+        timestamp < 0 ||
+        timestamp > MAX_EVENT_TIMESTAMP
+    ) {
+        throw invalidEvent("timestamp out of range");
+    }
+    return {
+        version,
+        id: incoming.id ?? crypto.randomUUID(),
+        type: incoming.type,
+        entityId: incoming.entityId.trim(),
+        entityVersion,
+        timestamp,
+        payload: incoming.payload,
+    };
+}
+
+/**
+ * The identity a gateway stamped on a request. Anything that is not a short
+ * printable string is ignored rather than stored, so a malformed header can
+ * never fail an append.
+ */
+export function normalizeActor(value: unknown): string | null {
+    if (typeof value !== "string") return null;
+    const actor = value.trim();
+    if (actor.length === 0 || actor.length > 320) return null;
+    // eslint-disable-next-line no-control-regex
+    return /[\u0000-\u001f\u007f]/.test(actor) ? null : actor;
+}
+
+export function canonicalJson(value: unknown): string {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value as Record<string, unknown>;
+        return `{${Object.keys(record)
+            .sort()
+            .map(
+                (key) =>
+                    `${JSON.stringify(key)}:${canonicalJson(record[key])}`,
+            )
+            .join(",")}}`;
+    }
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+        throw validationError("value is not JSON serializable");
+    }
+    return serialized;
+}
+
+function invalidEntityVersionChain(
+    entityId: string,
+    expected: number | undefined,
+    actual: number | undefined,
+): LedgerError {
+    return new LedgerError(409, {
+        error: "ValidationError",
+        code: "invalid_entity_version_chain",
+        message: "baseEntityVersion does not continue the entity version chain",
+        entityId,
+        expectedBaseEntityVersion: expected ?? null,
+        actualBaseEntityVersion: actual ?? null,
+    });
+}