@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/accesslayer/share-link/helpers.ts

@@ -0,0 +1,450 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+
+import type { ShareLinkOperationKind } from '@helpers/share-link-lifecycle';
+import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy/types';
+
+import type { ShareContentState, ShareLinkRecord, ShareLinkStatus } from '../../models/ShareLink';
+import type { Neo4jQueryResult, ShareLinkTransaction } from './transaction';
+import type {
+    ShareContentCleanupJobRecord,
+    ShareLinkOperationRecord,
+    ShareLinkOperationStatus,
+    ShareLinkReservationRecord,
+} from './types';
+
+type Neo4jNodeLike = {
+    properties?: Record<string, unknown>;
+};
+
+/** Converts a neo4j-driver Integer (or nested array) to plain JS values. */
+export const normalizeNeo4jValue = (value: unknown): unknown => {
+    if (value === undefined || value === null) return null;
+
+    if (typeof value === 'object') {
+        const maybeInteger = value as { toNumber?: () => number };
+
+        if (typeof maybeInteger.toNumber === 'function') {
+            return maybeInteger.toNumber();
+        }
+    }
+
+    if (Array.isArray(value)) return value.map(normalizeNeo4jValue);
+
+    return value;
+};
+
+export const normalizeProperties = (props: Record<string, unknown>): Record<string, unknown> =>
+    Object.fromEntries(
+        Object.entries(props).map(([key, value]) => [key, normalizeNeo4jValue(value)])
+    );
+
+/** Reads `rowIndex`'s node under `key` and returns normalized properties, or null. */
+export const readNodeProperties = (
+    result: Neo4jQueryResult,
+    key: string,
+    rowIndex = 0
+): Record<string, unknown> | null => {
+    const value = result.records[rowIndex]?.get(key);
+
+    if (!value || typeof value !== 'object') return null;
+
+    const props = (value as Neo4jNodeLike).properties;
+
+    return props ? normalizeProperties(props) : null;
+};
+
+const SHARE_LINK_STATUSES: readonly ShareLinkStatus[] = ['pending', 'active', 'stopped'];
+const SHARE_CONTENT_STATES: readonly ShareContentState[] = [
+    'staging',
+    'finalized',
+    'content_missing',
+];
+const OPERATION_KINDS: readonly ShareLinkOperationKind[] = ['create', 'update', 'revoke'];
+const OPERATION_STATUSES: readonly ShareLinkOperationStatus[] = [
+    'in_progress',
+    'committed',
+    'abandoned',
+];
+const CLEANUP_REASONS = ['superseded', 'abandoned', 'stopped'] as const;
+const CLEANUP_STATUSES = ['queued', 'claimed', 'completed'] as const;
+
+const isOneOf = <T extends string>(value: unknown, allowed: readonly T[]): value is T =>
+    typeof value === 'string' && (allowed as readonly string[]).includes(value);
+
+const asString = (value: unknown, fallback = ''): string =>
+    typeof value === 'string' ? value : fallback;
+
+const asNullableString = (value: unknown): string | null =>
+    typeof value === 'string' ? value : null;
+
+const asNumber = (value: unknown, fallback: number): number =>
+    typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+const asNullableNumber = (value: unknown): number | null =>
+    typeof value === 'number' && Number.isFinite(value) ? value : null;
+
+const asBoolean = (value: unknown, fallback: boolean): boolean =>
+    typeof value === 'boolean' ? value : fallback;
+
+const asNullableBoolean = (value: unknown): boolean | null =>
+    typeof value === 'boolean' ? value : null;
+
+export const toShareLinkRecord = (props: Record<string, unknown>): ShareLinkRecord => ({
+    id: asString(props.id),
+    namespace: asString(props.namespace),
+    ownerProfileId: asString(props.ownerProfileId),
+    version: asNumber(props.version, 1),
+    contentVersion: asNumber(props.contentVersion, 1),
+    attachmentId: asNullableString(props.attachmentId),
+    attachmentChunkCount: asNullableNumber(props.attachmentChunkCount),
+    generation: asNumber(props.generation, 1),
+    status: isOneOf(props.status, SHARE_LINK_STATUSES) ? props.status : 'pending',
+    contentState: isOneOf(props.contentState, SHARE_CONTENT_STATES)
+        ? props.contentState
+        : 'staging',
+    activeObjectRef: asNullableString(props.activeObjectRef),
+    activeObjectOperationId: asNullableString(props.activeObjectOperationId),
+    activeContentHash: asNullableString(props.activeContentHash),
+    activeContentBytes: asNullableNumber(props.activeContentBytes),
+    activeRecoveryHash: asNullableString(props.activeRecoveryHash),
+    lastOperationId: asNullableString(props.lastOperationId),
+    createdByClientRequestId: asNullableString(props.createdByClientRequestId),
+    title: asString(props.title),
+    note: asNullableString(props.note),
+    selectedCount: asNumber(props.selectedCount, 1),
+    expiresAt: asNullableString(props.expiresAt),
+    stoppedAt: asNullableString(props.stoppedAt),
+    viewCount: asNumber(props.viewCount, 0),
+    lastViewedAt: asNullableString(props.lastViewedAt),
+    passcodeHash: asNullableString(props.passcodeHash),
+    notifyOnView: asBoolean(props.notifyOnView, false),
+    minorPolicyIsMinor: asNullableBoolean(props.minorPolicyIsMinor),
+    minorPolicyResolved: asBoolean(props.minorPolicyResolved, false),
+    minorPolicyDefaultExpiryDays: asNumber(props.minorPolicyDefaultExpiryDays, 30),
+    minorPolicyViewCountingEnabled: asBoolean(props.minorPolicyViewCountingEnabled, false),
+    createdAt: asString(props.createdAt),
+    updatedAt: asString(props.updatedAt),
+});
+
+export const toShareLinkReservationRecord = (
+    props: Record<string, unknown>
+): ShareLinkReservationRecord => ({
+    shareId: asString(props.shareId),
+    namespace: asString(props.namespace),
+    ownerProfileId: asString(props.ownerProfileId),
+    opKind: isOneOf(props.opKind, OPERATION_KINDS) ? props.opKind : 'create',
+    clientRequestId: asString(props.clientRequestId),
+    requestHash: asString(props.requestHash),
+    operationId: asString(props.operationId),
+    objectRef: asNullableString(props.objectRef),
+    contentVersion: asNullableNumber(props.contentVersion),
+    attachmentId: asNullableString(props.attachmentId),
+    attachmentChunkCount: asNullableNumber(props.attachmentChunkCount),
+    baseVersion: asNumber(props.baseVersion, 1),
+    baseContentVersion: asNumber(props.baseContentVersion, 1),
+    contentHash: asNullableString(props.contentHash),
+    contentBytes: asNullableNumber(props.contentBytes),
+    recoveryHash: asNullableString(props.recoveryHash),
+    recoveryBytes: asNullableNumber(props.recoveryBytes),
+    title: asString(props.title),
+    note: asNullableString(props.note),
+    expiresAt: asNullableString(props.expiresAt),
+    selectedCount: asNumber(props.selectedCount, 1),
+    passcodeHash: asNullableString(props.passcodeHash),
+    notifyOnView: asBoolean(props.notifyOnView, false),
+    policy: {
+        isMinor: asNullableBoolean(props.policyIsMinor),
+        policyResolved: asBoolean(props.policyResolved, false),
+        defaultExpiryDays: asNumber(props.policyDefaultExpiryDays, 30) === 365 ? 365 : 30,
+        viewCountingEnabled: asBoolean(props.policyViewCountingEnabled, false),
+    },
+    generation: asNumber(props.generation, 1),
+    leaseOwner: asString(props.leaseOwner),
+    leaseExpiresAt: asString(props.leaseExpiresAt),
+    createdAt: asString(props.createdAt),
+    updatedAt: asString(props.updatedAt),
+});
+
+/** Legacy operation records have no policy ceiling; callers fall back to their reservation. */
+export const toShareLinkOperationPolicy = (
+    props: Record<string, unknown>
+): ShareLinkPolicySnapshot | null => {
+    if (typeof props.policyViewCountingEnabled !== 'boolean') return null;
+
+    return {
+        isMinor: asNullableBoolean(props.policyIsMinor),
+        policyResolved: asBoolean(props.policyResolved, false),
+        defaultExpiryDays: asNumber(props.policyDefaultExpiryDays, 30) === 365 ? 365 : 30,
+        viewCountingEnabled: props.policyViewCountingEnabled,
+    };
+};
+
+export const toShareLinkOperationRecord = (
+    props: Record<string, unknown>
+): ShareLinkOperationRecord => ({
+    namespace: asString(props.namespace),
+    ownerProfileId: asString(props.ownerProfileId),
+    opKind: isOneOf(props.opKind, OPERATION_KINDS) ? props.opKind : 'create',
+    clientRequestId: asString(props.clientRequestId),
+    operationId: asString(props.operationId),
+    shareId: asString(props.shareId),
+    requestHash: asString(props.requestHash),
+    status: isOneOf(props.status, OPERATION_STATUSES) ? props.status : 'in_progress',
+    resultJson: asNullableString(props.resultJson),
+    resultVersion: asNullableNumber(props.resultVersion),
+    createdAt: asString(props.createdAt),
+    updatedAt: asString(props.updatedAt),
+    pruneAfter: asString(props.pruneAfter),
+});
+
+export const toShareContentCleanupJobRecord = (
+    props: Record<string, unknown>
+): ShareContentCleanupJobRecord => ({
+    objectRef: asString(props.objectRef),
+    operationId: asString(props.operationId),
+    namespace: asString(props.namespace),
+    ownerProfileId: asString(props.ownerProfileId),
+    shareId: asString(props.shareId),
+    contentVersion: asNumber(props.contentVersion, 0),
+    reason: isOneOf(props.reason, CLEANUP_REASONS) ? props.reason : 'superseded',
+    status: isOneOf(props.status, CLEANUP_STATUSES) ? props.status : 'queued',
+    attempts: asNumber(props.attempts, 0),
+    nextAttemptAt: asString(props.nextAttemptAt),
+    claimToken: asNullableString(props.claimToken),
+    claimedBy: asNullableString(props.claimedBy),
+    claimExpiresAt: asNullableString(props.claimExpiresAt),
+    lastError: asNullableString(props.lastError),
+    createdAt: asString(props.createdAt),
+    updatedAt: asString(props.updatedAt),
+    completedAt: asNullableString(props.completedAt),
+});
+
+/** 32-byte opaque immutable LearnCloud object id (43-char base64url). */
+export const generateObjectRef = (): string => randomBytes(32).toString('base64url');
+
+/** Opaque, unique operation id used to bind a reservation to a worker's finalize. */
+export const generateOperationId = (): string => randomUUID();
+
+/** Opaque cleanup claim fence; a stale claimant can no longer complete the job. */
+export const generateClaimToken = (): string => randomUUID();
+
+export type ShareLinkOperationKey = {
+    namespace: string;
+    ownerProfileId: string;
+    opKind: ShareLinkOperationKind;
+    clientRequestId: string;
+};
+
+/**
+ * Acquires the share write lock.
+ *
+ * The property write is deliberate: once it commits, every other lifecycle
+ * transaction that targets this share blocks until this transaction ends, so a
+ * caller always reads status/version/reservation state under the lock.
+ */
+export const lockShare = async (
+    tx: ShareLinkTransaction,
+    shareId: string
+): Promise<Record<string, unknown> | null> => {
+    const result = await tx.run(
+        `MATCH (s:ShareLink {id: $shareId})
+         SET s.lockTick = coalesce(s.lockTick, 0) + 1
+         RETURN s`,
+        { shareId }
+    );
+
+    return readNodeProperties(result, 's');
+};
+
+export const readShareById = async (
+    tx: ShareLinkTransaction,
+    shareId: string
+): Promise<Record<string, unknown> | null> => {
+    const result = await tx.run('MATCH (s:ShareLink {id: $shareId}) RETURN s LIMIT 1', {
+        shareId,
+    });
+
+    return readNodeProperties(result, 's');
+};
+
+export const readReservation = async (
+    tx: ShareLinkTransaction,
+    shareId: string
+): Promise<Record<string, unknown> | null> => {
+    const result = await tx.run(
+        'MATCH (r:ShareLinkReservation {shareId: $shareId}) RETURN r LIMIT 1',
+        { shareId }
+    );
+
+    return readNodeProperties(result, 'r');
+};
+
+export const readOperation = async (
+    tx: ShareLinkTransaction,
+    key: ShareLinkOperationKey
+): Promise<Record<string, unknown> | null> => {
+    const result = await tx.run(
+        `MATCH (o:ShareLinkOperation {
+            namespace: $namespace,
+            ownerProfileId: $ownerProfileId,
+            opKind: $opKind,
+            clientRequestId: $clientRequestId
+         })
+         RETURN o LIMIT 1`,
+        key
+    );
+
+    return readNodeProperties(result, 'o');
+};
+
+export const readOperationByOperationId = async (
+    tx: ShareLinkTransaction,
+    operationId: string
+): Promise<Record<string, unknown> | null> => {
+    const result = await tx.run(
+        'MATCH (o:ShareLinkOperation {operationId: $operationId}) RETURN o LIMIT 1',
+        { operationId }
+    );
+
+    return readNodeProperties(result, 'o');
+};
+
+export type WriteOperationInput = ShareLinkOperationKey & {
+    operationId: string;
+    shareId: string;
+    requestHash: string;
+    now: string;
+    pruneAfter: string;
+    policy?: ShareLinkPolicySnapshot;
+};
+
+/**
+ * Creates or re-arms the idempotency record for an in-flight operation.
+ *
+ * The caller has already validated the request hash for an existing record, so
+ * overwriting the stored hash here is only a re-drive of an abandoned record.
+ */
+export const writeOperationInProgress = async (
+    tx: ShareLinkTransaction,
+    input: WriteOperationInput
+): Promise<void> => {
+    await tx.run(
+        `MERGE (o:ShareLinkOperation {
+            namespace: $namespace,
+            ownerProfileId: $ownerProfileId,
+            opKind: $opKind,
+            clientRequestId: $clientRequestId
+         })
+         ON CREATE SET o.createdAt = $now, o.pruneAfter = $pruneAfter
+         SET o.operationId = $operationId,
+             o.shareId = $shareId,
+             o.requestHash = $requestHash,
+             o.status = 'in_progress',
+             o.resultJson = null,
+             o.resultVersion = null,
+             o.updatedAt = $now
+         SET o += $policyProps`,
+        {
+            ...input,
+            policyProps: input.policy
+                ? {
+                      policyIsMinor: input.policy.isMinor,
+                      policyResolved: input.policy.policyResolved,
+                      policyDefaultExpiryDays: input.policy.defaultExpiryDays,
+                      policyViewCountingEnabled: input.policy.viewCountingEnabled,
+                  }
+                : {},
+        }
+    );
+};
+
+export const markOperationCommitted = async (
+    tx: ShareLinkTransaction,
+    input: ShareLinkOperationKey & {
+        operationId: string;
+        resultJson: string;
+        resultVersion: number;
+        now: string;
+        pruneAfter: string;
+    }
+): Promise<void> => {
+    await tx.run(
+        `MATCH (o:ShareLinkOperation {
+            namespace: $namespace,
+            ownerProfileId: $ownerProfileId,
+            opKind: $opKind,
+            clientRequestId: $clientRequestId
+         })
+         SET o.operationId = $operationId,
+             o.status = 'committed',
+             o.resultJson = $resultJson,
+             o.resultVersion = $resultVersion,
+             o.updatedAt = $now,
+             o.pruneAfter = $pruneAfter`,
+        input
+    );
+};
+
+export const markOperationAbandoned = async (
+    tx: ShareLinkTransaction,
+    key: ShareLinkOperationKey & { now: string }
+): Promise<void> => {
+    await tx.run(
+        `MATCH (o:ShareLinkOperation {
+            namespace: $namespace,
+            ownerProfileId: $ownerProfileId,
+            opKind: $opKind,
+            clientRequestId: $clientRequestId
+         })
+         SET o.status = 'abandoned', o.updatedAt = $now`,
+        key
+    );
+};
+
+export const deleteReservation = async (
+    tx: ShareLinkTransaction,
+    shareId: string
+): Promise<void> => {
+    await tx.run('MATCH (r:ShareLinkReservation {shareId: $shareId}) DELETE r', { shareId });
+};
+
+export type EnqueueCleanupJobInput = {
+    objectRef: string;
+    operationId: string;
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    reason: 'superseded' | 'abandoned' | 'stopped';
+    now: string;
+};
+
+/**
+ * Durable, exact-object cleanup enqueue. `MERGE` on the unique `objectRef` makes
+ * a retry idempotent; the repository never deletes LearnCloud content itself.
+ */
+export const enqueueCleanupJob = async (
+    tx: ShareLinkTransaction,
+    input: EnqueueCleanupJobInput
+): Promise<void> => {
+    await tx.run(
+        `MERGE (c:ShareContentCleanupJob {objectRef: $objectRef})
+         ON CREATE SET c.namespace = $namespace,
+             c.ownerProfileId = $ownerProfileId,
+             c.shareId = $shareId,
+             c.contentVersion = $contentVersion,
+             c.operationId = $operationId,
+             c.reason = $reason,
+             c.status = 'queued',
+             c.attempts = 0,
+             c.nextAttemptAt = $now,
+             c.claimToken = null,
+             c.claimedBy = null,
+             c.claimExpiresAt = null,
+             c.lastError = null,
+             c.completedAt = null,
+             c.createdAt = $now,
+             c.updatedAt = $now`,
+        input
+    );
+};

package/src/accesslayer/share-link/index.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './errors';
+export * from './reserve';
+export * from './finalize';
+export * from './abandon';
+export * from './revoke';
+export * from './read';
+export * from './list';
+export * from './cleanup';
+export * from './recovery';
+export * from './receipt';

package/src/accesslayer/share-link/list.ts

@@ -0,0 +1,162 @@
+import { SHARE_LINK_ID_BYTES, isCanonicalBase64Url } from '@learncard/types';
+
+import { neogma } from '@instance';
+
+import { readNodeProperties, toShareLinkRecord } from './helpers';
+import type { ListShareLinksInput, ListShareLinksResult, ShareLinkListCursor } from './types';
+import type { ShareLinkRecord } from '../../models/ShareLink';
+
+/**
+ * LC-2187 bounded owner-list repository.
+ *
+ * Contract:
+ * - Every query is scoped by the trusted `namespace` AND `ownerProfileId`; the
+ *   caller can never widen either through the cursor or any other field.
+ * - Keyset pagination over the immutable `(createdAt, id)` key. `createdAt` is
+ *   never mutated for a share and `id` is globally unique, so the total order is
+ *   stable and equal-timestamp records neither duplicate nor skip across pages.
+ *   There is no OFFSET and no unbounded fetch/sort in memory.
+ * - The cursor is a canonical, versioned encoding of exactly the two ordering
+ *   fields. It is an ORDERING HINT only: it never carries namespace, owner,
+ *   status or a query clause, and the current authenticated scope is always
+ *   applied independently. A cursor minted for another owner therefore cannot
+ *   reveal that owner's records; it can only advance the caller's own page.
+ * - `limit + 1` rows are fetched so `hasMore`/`nextCursor` are decided without a
+ *   count query. Limits are defensively bounded again here.
+ * - Pending (`staging`), active, retained-expired and stopped records are all
+ *   listed by owner. Listing is read-only: it never triggers cleanup, never
+ *   contacts public content, and never mutates a share.
+ *
+ * Concurrent insert/delete is deliberately not a snapshot: a page reflects the
+ * graph at read time, so a new share may appear and a deleted share may vanish
+ * between pages. Only the immutable ordering key is guaranteed stable.
+ */
+
+const CURSOR_VERSION = 1;
+const CURSOR_PREFIX = `v${CURSOR_VERSION}.`;
+const MAX_CURSOR_LENGTH = 512;
+const MAX_LIST_LIMIT = 50;
+const DEFAULT_LIST_LIMIT = 25;
+
+const isCanonicalIsoInstant = (value: string): boolean => {
+    const parsed = Date.parse(value);
+
+    if (!Number.isFinite(parsed)) return false;
+
+    try {
+        return new Date(parsed).toISOString() === value;
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * Canonical, versioned cursor over exactly `(createdAt, id)`.
+ *
+ * Encoding: `v1.` + base64url(UTF-8 JSON array `[createdAt, id]`). The version
+ * prefix lets a future encoding be rejected rather than mis-parsed, and the
+ * ordered-fields-only shape guarantees no database node, extra clause or private
+ * field can be smuggled through the cursor.
+ */
+export const encodeShareLinkListCursor = (cursor: ShareLinkListCursor): string =>
+    `${CURSOR_PREFIX}${Buffer.from(JSON.stringify([cursor.createdAt, cursor.id]), 'utf8').toString(
+        'base64url'
+    )}`;
+
+/**
+ * Strictly decodes a caller cursor. Returns `null` for anything malformed,
+ * oversized, non-canonical or impossible so the route can answer a fixed safe
+ * BAD_REQUEST without touching the graph.
+ */
+export const decodeShareLinkListCursor = (raw: unknown): ShareLinkListCursor | null => {
+    if (typeof raw !== 'string') return null;
+    if (raw.length === 0 || raw.length > MAX_CURSOR_LENGTH) return null;
+    if (!raw.startsWith(CURSOR_PREFIX)) return null;
+
+    const encoded = raw.slice(CURSOR_PREFIX.length);
+
+    if (encoded.length === 0) return null;
+
+    let json: string;
+    try {
+        const bytes = Buffer.from(encoded, 'base64url');
+
+        // Reject non-canonical base64url (padding/unused-bit variants) so one
+        // logical cursor has exactly one spelling.
+        if (bytes.toString('base64url') !== encoded) return null;
+
+        json = bytes.toString('utf8');
+    } catch {
+        return null;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(json);
+    } catch {
+        return null;
+    }
+
+    if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+
+    const [createdAt, id] = parsed;
+
+    if (typeof createdAt !== 'string' || !isCanonicalIsoInstant(createdAt)) return null;
+    if (!isCanonicalBase64Url(id, SHARE_LINK_ID_BYTES)) return null;
+
+    return { createdAt, id };
+};
+
+const boundLimit = (limit: number): number => {
+    if (!Number.isFinite(limit)) return DEFAULT_LIST_LIMIT;
+
+    return Math.min(Math.max(Math.trunc(limit), 1), MAX_LIST_LIMIT);
+};
+
+/**
+ * Reads one bounded page of the caller's own shares, newest first. A decoded
+ * cursor is the only accepted cursor form; the route decodes/validates the raw
+ * caller string before this point.
+ */
+export const listShareLinks = async (input: ListShareLinksInput): Promise<ListShareLinksResult> => {
+    const limit = boundLimit(input.limit);
+    const cursor = input.cursor ?? null;
+
+    const result = await neogma.queryRunner.run(
+        `MATCH (s:ShareLink {namespace: $namespace, ownerProfileId: $ownerProfileId})
+         WHERE $cursorCreatedAt IS NULL
+            OR s.createdAt < $cursorCreatedAt
+            OR (s.createdAt = $cursorCreatedAt AND s.id < $cursorId)
+         RETURN s
+         ORDER BY s.createdAt DESC, s.id DESC
+         LIMIT toInteger($limit)`,
+        {
+            namespace: input.namespace,
+            ownerProfileId: input.ownerProfileId,
+            cursorCreatedAt: cursor?.createdAt ?? null,
+            cursorId: cursor?.id ?? null,
+            limit: limit + 1,
+        }
+    );
+
+    const fetched: ShareLinkRecord[] = [];
+
+    for (let index = 0; index < result.records.length; index += 1) {
+        const props = readNodeProperties(result, 's', index);
+
+        if (props) fetched.push(toShareLinkRecord(props));
+    }
+
+    const hasMore = fetched.length > limit;
+    const records = hasMore ? fetched.slice(0, limit) : fetched;
+    const last = records[records.length - 1];
+
+    return {
+        records,
+        hasMore,
+        nextCursor:
+            hasMore && last
+                ? encodeShareLinkListCursor({ createdAt: last.createdAt, id: last.id })
+                : null,
+    };
+};