@learncard/network-brain-service 3.19.0 → 3.19.1

package/src/helpers/share-link-coordinator/types.ts

@@ -0,0 +1,353 @@
+import type {
+    AbandonRecoveredReservationInput,
+    AbandonRecoveredReservationResult,
+    AbandonReservationInput,
+    AbandonReservationResult,
+    ClaimCleanupJobsInput,
+    ClaimCleanupJobsResult,
+    ClaimRecoverableReservationInput,
+    ClaimRecoverableReservationResult,
+    CompleteCleanupJobInput,
+    CompleteCleanupJobResult,
+    CurrentShareContentResult,
+    DiscoverRecoverableReservationsInput,
+    DiscoverRecoverableReservationsResult,
+    FinalizeReservationInput,
+    FinalizeReservationResult,
+    GetCurrentShareContentInput,
+    GetShareLinkInput,
+    RecoveryClaimRejection,
+    ReserveCreateInput,
+    ReserveReplacementInput,
+    ReserveShareLinkResult,
+    RevokeShareLinkInput,
+    RevokeShareLinkResult,
+    ShareLinkRecoveryKey,
+    ShareLinkRecoveryTarget,
+    ShareLinkReservationRecord,
+} from '../../accesslayer/share-link';
+import type {
+    ShareContentClient,
+    ShareContentClientErrorCode,
+    ShareContentClientResult,
+    ShareContentContentProjection,
+    ShareContentPutRequest,
+    ShareContentRecoveryProjection,
+} from '../share-content-client/types';
+import type { ShareEnvelope } from '@learncard/types';
+import type { ShareLinkRecord } from '../../models/ShareLink';
+import type { ShareLinkPolicyResolver } from '../share-link-policy/types';
+
+/**
+ * Bounded, monotonic wall-clock budget shared by the recovery and cleanup runners.
+ *
+ * `exhausted()` is true once the remaining time is at or below the reserve the
+ * orchestrator needs to finalize (write telemetry, return a summary). A runner
+ * checks it before every claim so it never starts work it cannot finish; it must
+ * never be implemented with `Promise.race` because that would leave graph or
+ * remote mutations running untracked after the pass returns.
+ */
+export type MaintenanceBudget = {
+    remainingMs: () => number;
+    exhausted: () => boolean;
+    /**
+     * Optional finalization reserve in milliseconds. Direct/legacy callers omit
+     * it (only `exhausted()` is enforced). The maintenance pass supplies it so a
+     * runner can additionally require the remaining time to cover the whole next
+     * unit's bounded graph/HTTP calls before it starts one.
+     */
+    reserveMs?: () => number;
+};
+
+/**
+ * Structural type of the C3 lifecycle repository consumed by the coordinator.
+ *
+ * It is a type-only import of the reviewed lifecycle API: production wiring
+ * passes the real functions, tests pass fakes. The coordinator never performs
+ * network I/O inside a Neo4j transaction because it always awaits the
+ * repository call first and only then drives the LearnCloud client.
+ */
+export type ShareLinkLifecycleRepository = {
+    reserveCreate: (input: ReserveCreateInput) => Promise<ReserveShareLinkResult>;
+    reserveReplacement: (input: ReserveReplacementInput) => Promise<ReserveShareLinkResult>;
+    finalizeReservation: (input: FinalizeReservationInput) => Promise<FinalizeReservationResult>;
+    abandonReservation: (input: AbandonReservationInput) => Promise<AbandonReservationResult>;
+    revokeShareLink: (input: RevokeShareLinkInput) => Promise<RevokeShareLinkResult>;
+    getShareLink: (input: GetShareLinkInput) => Promise<ShareLinkRecord | null>;
+    getCurrentShareContent: (
+        input: GetCurrentShareContentInput
+    ) => Promise<CurrentShareContentResult>;
+    claimCleanupJobs: (input: ClaimCleanupJobsInput) => Promise<ClaimCleanupJobsResult>;
+    completeCleanupJob: (input: CompleteCleanupJobInput) => Promise<CompleteCleanupJobResult>;
+};
+
+/** Dependencies injected into the coordinator. */
+export type ShareLinkCoordinatorDependencies = {
+    repository: ShareLinkLifecycleRepository;
+    client: Pick<ShareContentClient, 'put' | 'get' | 'stat' | 'delete' | 'readRecovery'>;
+    /** Stable bounded lease owner for this worker/process. */
+    leaseOwner: string;
+    leaseMs?: number;
+    now?: () => Date;
+    /**
+     * Server-side policy resolver. Omitted dependencies fall back to the
+     * conservative unknown-age policy (30 days, no views), never to adult.
+     */
+    policyResolver?: ShareLinkPolicyResolver;
+};
+
+/** Trusted server-side context. Never taken from the caller's request body. */
+export type ShareOwnerContext = {
+    namespace: string;
+    ownerProfileId: string;
+};
+
+export type ShareContentPendingReason =
+    | 'upload_unavailable'
+    | 'stat_unavailable'
+    | 'stat_missing'
+    | 'stat_mismatch'
+    | 'finalize_unavailable';
+
+export type ShareLinkCommitResult =
+    | { status: 'committed'; share: ShareLinkRecord }
+    | { status: 'replayed'; share: ShareLinkRecord; recorded: ShareLinkRecord }
+    | {
+          status: 'pending';
+          reservation: ShareLinkReservationRecord;
+          reason: ShareContentPendingReason;
+      };
+
+export type ShareLinkRevokeResult = {
+    status: 'revoked' | 'already_stopped';
+    share: ShareLinkRecord;
+    cleanupQueuedFor: string[];
+};
+
+export type ShareLinkResumeResult =
+    | { status: 'committed'; share: ShareLinkRecord }
+    | { status: 'replayed'; share: ShareLinkRecord }
+    | {
+          status: 'pending';
+          reservation: ShareLinkReservationRecord;
+          reason: ShareContentPendingReason;
+      }
+    | { status: 'abandoned'; cleanupQueuedFor: string | null };
+
+/** Opaque content payload supplied on a stateless retry. */
+export type ShareContentPayload = {
+    envelope: ShareEnvelope;
+    ownerEncryptedRecovery: Record<string, unknown>;
+};
+
+/**
+ * INTERNAL ONLY. A pending reservation descriptor may only be produced by this
+ * server from a prior coordinator call; it must never be accepted from a client
+ * request body. Durable restart recovery must instead use the persisted-state
+ * entry points (`runShareLinkRecoveryOnce` / `recoverShareLinkOperation`), which
+ * never trust a caller-supplied object ref, hash, generation or lease.
+ */
+export type PendingShareContentOperation = {
+    reservation: ShareLinkReservationRecord;
+};
+
+export type ShareLinkCoordinatorErrorCode =
+    | 'INVALID_INPUT'
+    | 'NOT_FOUND'
+    | 'CONFLICT'
+    | 'UNAUTHORIZED'
+    | 'SIGNING_FAILED'
+    | 'PAYLOAD_TOO_LARGE'
+    | 'UNAVAILABLE'
+    | 'LEASE_EXPIRED'
+    | 'STALE_GENERATION'
+    | 'OPERATION_IN_FLIGHT'
+    | 'PRECONDITION_FAILED'
+    | 'UNEXPECTED';
+
+export class ShareLinkCoordinatorError extends Error {
+    readonly code: ShareLinkCoordinatorErrorCode;
+
+    constructor(code: ShareLinkCoordinatorErrorCode, message: string) {
+        super(message);
+        this.name = 'ShareLinkCoordinatorError';
+        this.code = code;
+    }
+}
+
+/**
+ * Fixed, non-sensitive cleanup outcome categories. Client transport codes are
+ * reused verbatim; the extra literals cover a claim that could not be confirmed
+ * and a throwing client/complete dependency. No value carries an identifier.
+ */
+export type ShareCleanupCategory =
+    | ShareContentClientErrorCode
+    | 'claim_lost'
+    | 'claim_error'
+    | 'client_error'
+    | 'budget_exhausted';
+
+/**
+ * One-shot cleanup runner result.
+ *
+ * `skipped` is a count, never a per-item array: a deterministic delete failure
+ * must not leak object refs, share/owner ids or exception text into telemetry.
+ * `categories` is a fixed histogram drawn only from `ShareCleanupCategory`.
+ */
+export type CleanupRunSummary = {
+    claimed: number;
+    completed: number;
+    retried: number;
+    claimLost: number;
+    skipped: number;
+    categories: Partial<Record<ShareCleanupCategory, number>>;
+};
+
+export type CleanupRunnerDependencies = {
+    repository: Pick<ShareLinkLifecycleRepository, 'claimCleanupJobs' | 'completeCleanupJob'>;
+    client: Pick<ShareContentClient, 'delete'>;
+    claimant: string;
+    /** Required explicit namespace; cleanup is never global. */
+    namespace: string;
+    limit?: number;
+    claimMs?: number;
+    /**
+     * Max jobs per claim transaction. The scheduled maintenance pass sets this to
+     * 1 so a deadline cannot strand a whole claimed batch; the default preserves
+     * the reviewed one-shot batch behaviour.
+     */
+    claimBatchSize?: number;
+    /** Optional bounded budget; stops before claiming work it cannot finish. */
+    budget?: MaintenanceBudget;
+    /** Bounded managed-transaction timeout for each claim/complete unit. */
+    transactionTimeoutMs?: number;
+    /**
+     * Configured HTTP allowance for one bounded delete. Only used for whole-unit
+     * admission; the transport timeout itself is fixed when the client is built.
+     */
+    requestTimeoutMs?: number;
+    /** Maintenance-only: single explicit graph attempt with no inline retry. */
+    noInlineRetry?: boolean;
+    now?: () => Date;
+};
+
+/**
+ * Structural type of the durable reservation recovery repository.
+ *
+ * Recovery authority is always loaded from persisted Brain state: the runner is
+ * handed a namespace (bounded discovery) or an exact scoped key, never a
+ * serialized caller reservation. The coordinator only calls `finalizeReservation`
+ * after that repository call returns, so no remote I/O happens inside a Neo4j
+ * transaction.
+ */
+export type ShareLinkRecoveryRepository = {
+    discoverRecoverableReservations: (
+        input: DiscoverRecoverableReservationsInput
+    ) => Promise<DiscoverRecoverableReservationsResult>;
+    readShareLinkRecoveryTarget: (input: ShareLinkRecoveryKey) => Promise<ShareLinkRecoveryTarget>;
+    claimRecoverableReservation: (
+        input: ClaimRecoverableReservationInput
+    ) => Promise<ClaimRecoverableReservationResult>;
+    abandonRecoveredReservation: (
+        input: AbandonRecoveredReservationInput
+    ) => Promise<AbandonRecoveredReservationResult>;
+    finalizeReservation: (input: FinalizeReservationInput) => Promise<FinalizeReservationResult>;
+};
+
+/**
+ * Bounded, non-sensitive recovery categories. These are the only per-item
+ * outcomes a runner summary ever exposes; records, ciphertext, owner ids and
+ * object refs never leave the repository call.
+ */
+export type ShareRecoveryCategory =
+    | 'finalized'
+    | 'abandoned_missing'
+    | 'abandoned_tombstone'
+    | 'deferred_stat_mismatch'
+    | 'deferred_stat_transient'
+    | 'deferred_stat_error'
+    | 'deferred_finalize'
+    | 'claim_lost'
+    | 'malformed_binding'
+    | 'budget_exhausted';
+
+/** Aggregate result of one bounded recovery pass; no per-item identifiers. */
+export type ShareRecoveryRunSummary = {
+    discovered: number;
+    claimed: number;
+    finalized: number;
+    abandoned: number;
+    deferred: number;
+    claimLost: number;
+    anomalies: number;
+    categories: Partial<Record<ShareRecoveryCategory, number>>;
+};
+
+export type RecoveryRunnerDependencies = {
+    repository: ShareLinkRecoveryRepository;
+    client: Pick<ShareContentClient, 'stat'>;
+    /** Stable bounded lease owner for this recovery worker/process. */
+    claimant: string;
+    /** Required explicit namespace; discovery is never global. */
+    namespace: string;
+    limit?: number;
+    leaseMs?: number;
+    /** Optional bounded budget; stops before claiming work it cannot finish. */
+    budget?: MaintenanceBudget;
+    /** Bounded transaction timeout propagated to every recovery graph path. */
+    transactionTimeoutMs?: number;
+    /**
+     * Configured HTTP allowance for one bounded stat. Only used for whole-unit
+     * admission; the transport timeout itself is fixed when the client is built.
+     */
+    requestTimeoutMs?: number;
+    /** Maintenance-only: single explicit graph attempt with no inline retry. */
+    noInlineRetry?: boolean;
+    now?: () => Date;
+};
+
+/** Scoped-key recovery result. Internal only; never returned by a public route. */
+export type ScopedShareRecoveryResult =
+    | { status: 'committed'; share: ShareLinkRecord }
+    | { status: 'abandoned' }
+    | { status: 'deferred'; category: ShareRecoveryCategory }
+    | { status: 'absent' }
+    | { status: 'not_claimable'; reason: RecoveryClaimRejection };
+
+export type ShareLinkCoordinator = {
+    createShareLink: (
+        request: unknown,
+        context: ShareOwnerContext
+    ) => Promise<ShareLinkCommitResult>;
+    updateShareLink: (
+        request: unknown,
+        context: ShareOwnerContext
+    ) => Promise<ShareLinkCommitResult>;
+    revokeShareLink: (
+        request: unknown,
+        context: ShareOwnerContext
+    ) => Promise<ShareLinkRevokeResult>;
+    resumePendingOperation: (
+        pending: PendingShareContentOperation,
+        content?: ShareContentPayload
+    ) => Promise<ShareLinkResumeResult>;
+    abandonPendingOperation: (
+        pending: PendingShareContentOperation
+    ) => Promise<AbandonReservationResult>;
+    getShareLink: (shareId: string, context: ShareOwnerContext) => Promise<ShareLinkRecord | null>;
+    getActiveShareContent: (
+        shareId: string,
+        context: ShareOwnerContext
+    ) => Promise<CurrentShareContentResult>;
+    fetchShareContent: (
+        shareId: string,
+        context: ShareOwnerContext,
+        options?: { allowExpired?: boolean }
+    ) => Promise<ShareContentClientResult<ShareContentContentProjection>>;
+    readOwnerRecovery: (
+        shareId: string,
+        context: ShareOwnerContext
+    ) => Promise<ShareContentClientResult<ShareContentRecoveryProjection>>;
+};
+
+export type { ShareContentPutRequest };

package/src/helpers/share-link-lifecycle/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './request-hash.helpers';
+export * from './lease.helpers';
+export * from './recovery.helpers';

package/src/helpers/share-link-lifecycle/lease.helpers.ts

@@ -0,0 +1,35 @@
+import {
+    SHARE_LINK_CLEANUP_BASE_BACKOFF_MS,
+    SHARE_LINK_CLEANUP_MAX_BACKOFF_MS,
+    SHARE_LINK_DEFAULT_LEASE_MS,
+} from './types';
+
+/** ISO timestamp `leaseMs` milliseconds after `now`. */
+export const computeLeaseExpiry = (
+    now: Date,
+    leaseMs: number = SHARE_LINK_DEFAULT_LEASE_MS
+): string => new Date(now.getTime() + Math.max(0, Math.trunc(leaseMs))).toISOString();
+
+/**
+ * A lease is active only while `now` is strictly before its expiry. At the exact
+ * expiry instant the lease has lapsed so a stale worker cannot finalize.
+ */
+export const isLeaseActive = (leaseExpiresAt: string | null, now: Date): boolean => {
+    if (!leaseExpiresAt) return false;
+
+    const expiry = Date.parse(leaseExpiresAt);
+
+    return Number.isFinite(expiry) && now.getTime() < expiry;
+};
+
+/**
+ * Exponential cleanup backoff capped at one day. `attempts` is the number of
+ * completed retry cycles already recorded on the job (starts at 0 for a new job,
+ * so the first retry waits one base interval).
+ */
+export const computeCleanupBackoffMs = (attempts: number): number => {
+    const safeAttempts = Number.isSafeInteger(attempts) && attempts > 0 ? attempts : 0;
+    const backoff = SHARE_LINK_CLEANUP_BASE_BACKOFF_MS * 2 ** safeAttempts;
+
+    return Math.min(backoff, SHARE_LINK_CLEANUP_MAX_BACKOFF_MS);
+};

package/src/helpers/share-link-lifecycle/recovery.helpers.ts

@@ -0,0 +1,173 @@
+import type { ShareLinkOperationKind } from './types';
+
+/**
+ * Bounded discovery batch for durable reservation recovery.
+ *
+ * The runner must never enumerate an unbounded set: an operator gets one capped
+ * pass, and any remaining expired work is picked up by a later pass after its
+ * lease lapses again. The hard cap matches the cleanup-job batch cap.
+ */
+export const SHARE_LINK_RECOVERY_DEFAULT_BATCH = 25;
+export const SHARE_LINK_RECOVERY_MAX_BATCH = 100;
+
+/** Clamps a caller-supplied recovery batch into the documented 1..100 window. */
+export const clampShareLinkRecoveryBatch = (limit: number | undefined): number => {
+    if (!Number.isSafeInteger(limit) || (limit as number) < 1) {
+        return SHARE_LINK_RECOVERY_DEFAULT_BATCH;
+    }
+
+    return Math.min(limit as number, SHARE_LINK_RECOVERY_MAX_BATCH);
+};
+
+/** Exact scoped recovery key, always derived from persisted Brain state. */
+export type ShareLinkRecoveryKeyShape = {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    operationId: string;
+};
+
+/** Outcome of checking one persisted record against an exact scoped key. */
+export type ShareLinkRecoveryBindingCheck = 'ok' | 'binding_mismatch' | 'malformed_binding';
+
+const RESERVATION_OP_KINDS: readonly ShareLinkOperationKind[] = ['create', 'update'];
+const OPERATION_STATUSES = ['in_progress', 'committed', 'abandoned'] 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 isNonEmptyString = (value: unknown): value is string =>
+    typeof value === 'string' && value.length > 0;
+
+const isPositiveSafeInteger = (value: unknown): value is number =>
+    Number.isSafeInteger(value) && (value as number) >= 1;
+
+const isNonNegativeSafeInteger = (value: unknown): value is number =>
+    Number.isSafeInteger(value) && (value as number) >= 0;
+
+const isTimestamp = (value: unknown): value is string =>
+    typeof value === 'string' && Number.isFinite(Date.parse(value));
+
+const isAbsentOrNull = (value: unknown): boolean => value === undefined || value === null;
+
+/**
+ * Validates a persisted `:ShareLinkReservation` against an exact scoped key.
+ *
+ * Any missing/typed-wrong core field, an inconsistent object/content tuple, or a
+ * content binding without its hashes and byte counts is `malformed_binding` and
+ * must never be reclaimed. A well-formed record that simply does not match the
+ * key is `binding_mismatch`, which is an expected stale/foreign selection rather
+ * than corruption.
+ */
+export const classifyReservationBinding = (
+    props: Record<string, unknown>,
+    key: ShareLinkRecoveryKeyShape
+): ShareLinkRecoveryBindingCheck => {
+    if (
+        !isNonEmptyString(props.shareId) ||
+        !isNonEmptyString(props.namespace) ||
+        !isNonEmptyString(props.ownerProfileId) ||
+        !isNonEmptyString(props.operationId) ||
+        !isNonEmptyString(props.clientRequestId) ||
+        !isNonEmptyString(props.leaseOwner) ||
+        !isPositiveSafeInteger(props.generation) ||
+        !isPositiveSafeInteger(props.baseVersion) ||
+        !isPositiveSafeInteger(props.baseContentVersion) ||
+        !isTimestamp(props.leaseExpiresAt)
+    ) {
+        return 'malformed_binding';
+    }
+
+    if (!isOneOf(props.opKind, RESERVATION_OP_KINDS)) return 'malformed_binding';
+
+    const hasObject = !isAbsentOrNull(props.objectRef);
+    const hasContentVersion = !isAbsentOrNull(props.contentVersion);
+
+    if (hasObject !== hasContentVersion) return 'malformed_binding';
+
+    if (hasObject) {
+        if (
+            !isNonEmptyString(props.objectRef) ||
+            !isPositiveSafeInteger(props.contentVersion) ||
+            !isNonEmptyString(props.contentHash) ||
+            !isNonNegativeSafeInteger(props.contentBytes) ||
+            !isNonEmptyString(props.recoveryHash) ||
+            !isNonNegativeSafeInteger(props.recoveryBytes)
+        ) {
+            return 'malformed_binding';
+        }
+    } else if (
+        !isAbsentOrNull(props.contentHash) ||
+        !isAbsentOrNull(props.contentBytes) ||
+        !isAbsentOrNull(props.recoveryHash) ||
+        !isAbsentOrNull(props.recoveryBytes)
+    ) {
+        return 'malformed_binding';
+    }
+
+    if (
+        props.namespace !== key.namespace ||
+        props.ownerProfileId !== key.ownerProfileId ||
+        props.shareId !== key.shareId ||
+        props.operationId !== key.operationId
+    ) {
+        return 'binding_mismatch';
+    }
+
+    return 'ok';
+};
+
+/** Expected binding for a reservation's idempotency `:ShareLinkOperation` record. */
+export type ShareLinkRecoveryOperationExpectation = {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    operationId: string;
+    opKind?: string;
+    clientRequestId?: string;
+};
+
+/**
+ * Validates a persisted `:ShareLinkOperation` against the reservation it must
+ * drive. A missing/wrong-typed field or an unknown status is `malformed_binding`;
+ * a well-formed record bound to a different operation is `binding_mismatch`.
+ */
+export const classifyOperationBinding = (
+    props: Record<string, unknown>,
+    expected: ShareLinkRecoveryOperationExpectation
+): ShareLinkRecoveryBindingCheck => {
+    if (
+        !isNonEmptyString(props.namespace) ||
+        !isNonEmptyString(props.ownerProfileId) ||
+        !isNonEmptyString(props.shareId) ||
+        !isNonEmptyString(props.operationId) ||
+        !isNonEmptyString(props.opKind) ||
+        !isNonEmptyString(props.clientRequestId)
+    ) {
+        return 'malformed_binding';
+    }
+
+    if (!isOneOf(props.status, OPERATION_STATUSES)) return 'malformed_binding';
+
+    if (
+        props.namespace !== expected.namespace ||
+        props.ownerProfileId !== expected.ownerProfileId ||
+        props.shareId !== expected.shareId ||
+        props.operationId !== expected.operationId
+    ) {
+        return 'binding_mismatch';
+    }
+
+    if (expected.opKind !== undefined && props.opKind !== expected.opKind) {
+        return 'binding_mismatch';
+    }
+
+    if (
+        expected.clientRequestId !== undefined &&
+        props.clientRequestId !== expected.clientRequestId
+    ) {
+        return 'binding_mismatch';
+    }
+
+    return 'ok';
+};

package/src/helpers/share-link-lifecycle/request-hash.helpers.ts

@@ -0,0 +1,130 @@
+import { createHash, createHmac } from 'node:crypto';
+
+import { getShareLinkRequestHashRuntimeEnvironment } from '@environment';
+
+import type { ShareLinkOperationKind } from './types';
+
+/**
+ * Deterministic JSON encoding used for the canonical operation request hash.
+ *
+ * Object keys are sorted recursively so two semantically identical requests that
+ * differ only in key insertion order hash the same. Values that are not valid JSON
+ * (undefined, functions, bigint, symbols) are rejected instead of being silently
+ * dropped: a dropped field would weaken the "same request id, different request"
+ * conflict check.
+ */
+export const canonicalizeJson = (
+    value: unknown,
+    ancestors = new Set<object>(),
+    depth = 0
+): string => {
+    if (depth > 32) throw new TypeError('canonical JSON exceeds depth bound');
+    if (value === null) return 'null';
+
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isSafeInteger(value) || Object.is(value, -0)) {
+                throw new TypeError('canonicalizeJson only supports finite numbers');
+            }
+            return JSON.stringify(value);
+        case 'string':
+            return JSON.stringify(value);
+        case 'object': {
+            if (ancestors.has(value)) throw new TypeError('cyclic JSON');
+            ancestors.add(value);
+            if (Array.isArray(value)) {
+                try {
+                    const entries: string[] = [];
+                    for (let i = 0; i < value.length; i++) {
+                        if (!(i in value)) throw new TypeError('sparse JSON array');
+                        entries.push(canonicalizeJson(value[i], ancestors, depth + 1));
+                    }
+                    return `[${entries.join(',')}]`;
+                } finally {
+                    ancestors.delete(value);
+                }
+            }
+            if (
+                Object.getPrototypeOf(value) !== Object.prototype &&
+                Object.getPrototypeOf(value) !== null
+            ) {
+                throw new TypeError('only plain JSON objects supported');
+            }
+
+            const record = value as Record<string, unknown>;
+            const keys = Object.keys(record).sort();
+            const entries = keys
+                .filter(key => record[key] !== undefined)
+                .map(
+                    key =>
+                        `${JSON.stringify(key)}:${canonicalizeJson(record[key], ancestors, depth + 1)}`
+                );
+
+            ancestors.delete(value);
+            return `{${entries.join(',')}}`;
+        }
+        default:
+            throw new TypeError(`canonicalizeJson cannot encode a ${typeof value} value`);
+    }
+};
+
+/**
+ * Dedicated key for operation fingerprints. It must be stable across every Brain
+ * instance and deploy, otherwise an in-flight retry could become a conflict.
+ *
+ * Test runs use a fixed, test-only key. Enabled non-test deployments must
+ * provision an independent secret before serving share-link owner requests.
+ */
+export const getShareLinkRequestHashSecret = (): string => {
+    const runtime = getShareLinkRequestHashRuntimeEnvironment();
+    const secret = runtime.SHARE_LINK_REQUEST_HASH_SECRET;
+    if (secret && Buffer.byteLength(secret, 'utf8') >= 32) return secret;
+    if (runtime.NODE_ENV === 'test') return 'share-link-test-only-request-hash-secret';
+    throw new Error('SHARE_LINK_REQUEST_HASH_SECRET must contain at least 32 bytes');
+};
+
+/**
+ * Canonical fingerprint of the full validated request.
+ *
+ * The caller passes the *validated* request including the opaque envelope and the
+ * owner-encrypted recovery: the hash therefore covers the encrypted recovery even
+ * though no ciphertext is ever persisted in Neo4j. `clientRequestId` is the
+ * operation key identity and is deliberately excluded from the payload hash; all
+ * other fields, including `opKind`, are covered. Protected requests use a
+ * server-keyed HMAC so a persisted fingerprint cannot become a fast offline
+ * oracle for a short passcode. Unprotected requests retain the previous SHA-256
+ * format so their in-flight operation retries remain compatible.
+ */
+export const computeShareLinkRequestHash = (
+    opKind: ShareLinkOperationKind,
+    request: Record<string, unknown>
+): string => {
+    const { clientRequestId: _clientRequestId, ...requestPayload } = request;
+
+    const canonical = canonicalizeJson({ opKind, request: requestPayload });
+    if (typeof requestPayload.passcode !== 'string') {
+        return createHash('sha256').update(canonical).digest('hex');
+    }
+    return createHmac('sha256', getShareLinkRequestHashSecret())
+        .update('share-link-request:protected:v2\0')
+        .update(canonical)
+        .digest('hex');
+};
+
+/** Digest of validated opaque content, computable before reserving object IDs.
+ * Compare this with LearnCloud stat.payloadHash, not its identity-bound contentHash.
+ */
+export const computeShareLinkPayloadHash = (payload: {
+    envelope: unknown;
+    ownerEncryptedRecovery: unknown;
+}): string =>
+    createHash('sha256')
+        .update(
+            canonicalizeJson({
+                envelope: payload.envelope,
+                ownerEncryptedRecovery: payload.ownerEncryptedRecovery,
+            })
+        )
+        .digest('hex');