@learncard/network-brain-service 3.19.0 → 4.0.0

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

@@ -0,0 +1,58 @@
+/**
+ * LC-2187 share-link lifecycle constants and literals.
+ *
+ * This module is intentionally storage- and transport-agnostic: routes, the
+ * LearnCloud client and the reconciliation worker all derive their bounds from
+ * here so the Brain repository and the tests agree on one set of numbers.
+ */
+
+/** Operation kinds that are bound to an idempotency record. */
+export type ShareLinkOperationKind = 'create' | 'update' | 'revoke';
+
+export const SHARE_LINK_OPERATION_KINDS: readonly ShareLinkOperationKind[] = [
+    'create',
+    'update',
+    'revoke',
+];
+
+/**
+ * Default bounded lease for one in-flight share content operation. A worker that
+ * cannot finish staging + finalize within the lease loses its fence and must not
+ * commit; a later reservation supersedes it with a higher generation.
+ */
+export const SHARE_LINK_DEFAULT_LEASE_MS = 2 * 60 * 1000;
+
+/**
+ * Retain completed operation records for 30 days.
+ *
+ * Pruning is an explicit operator action, not an automatic replay path. After a
+ * record is pruned, object-reference uniqueness, the share version compare-and-set
+ * and the `stopped` terminal state still prevent a replay from overwriting newer
+ * content.
+ */
+export const SHARE_LINK_OPERATION_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Cleanup retry backoff bounds (exponential, capped). */
+export const SHARE_LINK_CLEANUP_BASE_BACKOFF_MS = 30 * 1000;
+export const SHARE_LINK_CLEANUP_MAX_BACKOFF_MS = 24 * 60 * 60 * 1000;
+
+/** Default cap on cleanup jobs claimed in one bounded batch. */
+export const SHARE_LINK_CLEANUP_DEFAULT_BATCH = 25;
+export const SHARE_LINK_CLEANUP_MAX_BATCH = 100;
+
+/** Default lease for a claimed cleanup job. */
+export const SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS = 5 * 60 * 1000;
+
+/**
+ * Hard bounds for a caller-supplied cleanup claim lease. A configured
+ * maintenance lease is clamped into this window so a bad deployment cannot hold
+ * (or instantly drop) work; the repository default is unchanged.
+ */
+export const SHARE_LINK_CLEANUP_MIN_CLAIM_MS = 1_000;
+export const SHARE_LINK_CLEANUP_MAX_CLAIM_MS = 30 * 60 * 1000;
+
+/** Reasons a durable cleanup job can be created. */
+export type ShareContentCleanupReason = 'superseded' | 'abandoned' | 'stopped';
+
+/** Lifecycle status of a durable cleanup job. */
+export type ShareContentCleanupStatus = 'queued' | 'claimed' | 'completed';

package/src/helpers/share-link-maintenance/budget.ts

@@ -0,0 +1,63 @@
+import type { MaintenanceBudget } from '../share-link-coordinator';
+
+/**
+ * Monotonic wall-clock budget for one maintenance pass.
+ *
+ * The runner checks `exhausted()` before each claim; once the remaining time is
+ * at or below `finalizeReserveMs` it must stop starting new graph/remote work so
+ * the pass can still log and return a summary. This is a cooperative deadline,
+ * not a hard kill: it never uses `Promise.race`, which would leave an untracked
+ * mutation running after the pass returned.
+ */
+export type MaintenancePassBudget = MaintenanceBudget & {
+    elapsedMs: () => number;
+    configuredMs: number;
+};
+
+const defaultMonotonicNow = (): number =>
+    typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+
+/**
+ * Resolve the pass budget from a Lambda remaining-time value.
+ *
+ * `undefined` means "no Lambda signal" and keeps the configured budget. Any
+ * other value failing the finite/positive check — NaN, Infinity, negative or
+ * zero — fails closed to a zero budget so the pass does no work.
+ */
+export const resolveMaintenanceBudgetMs = (
+    configuredBudgetMs: number,
+    remainingTimeMs: number | undefined
+): number => {
+    if (remainingTimeMs === undefined) return configuredBudgetMs;
+    if (!Number.isFinite(remainingTimeMs) || remainingTimeMs <= 0) return 0;
+
+    return Math.min(configuredBudgetMs, Math.trunc(remainingTimeMs));
+};
+
+export const createMaintenancePassBudget = (input: {
+    budgetMs: number;
+    finalizeReserveMs: number;
+    monotonicNow?: () => number;
+}): MaintenancePassBudget => {
+    const monotonicNow = input.monotonicNow ?? defaultMonotonicNow;
+    const configuredMs = Number.isFinite(input.budgetMs)
+        ? Math.max(0, Math.trunc(input.budgetMs))
+        : 0;
+    const reserveMs = Number.isFinite(input.finalizeReserveMs)
+        ? Math.max(0, Math.trunc(input.finalizeReserveMs))
+        : 0;
+    const startedAt = monotonicNow();
+    const deadline = startedAt + configuredMs;
+
+    const remainingMs = (): number => deadline - monotonicNow();
+
+    return {
+        configuredMs,
+        elapsedMs: () => monotonicNow() - startedAt,
+        remainingMs,
+        reserveMs: () => reserveMs,
+        exhausted: () => remainingMs() <= reserveMs,
+    };
+};

package/src/helpers/share-link-maintenance/config.ts

@@ -0,0 +1,312 @@
+import {
+    SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MAX_BATCH,
+    SHARE_LINK_CLEANUP_MAX_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MIN_CLAIM_MS,
+    SHARE_LINK_DEFAULT_LEASE_MS,
+} from '../share-link-lifecycle';
+import {
+    SHARE_LINK_RECOVERY_DEFAULT_BATCH,
+    SHARE_LINK_RECOVERY_MAX_BATCH,
+} from '../share-link-lifecycle/recovery.helpers';
+import { validateShareContentOrigin } from '../share-content-client/config';
+import type { ShareLinkMaintenanceConfig, ShareLinkMaintenanceConfigResolution } from './types';
+
+/**
+ * Operator-facing configuration for the automatic share-link maintenance pass.
+ *
+ * Every value is read and validated here rather than in the global environment
+ * schema so malformed maintenance settings fail closed to a fixed category
+ * instead of preventing the whole Brain service from booting. Absent or
+ * invalid configuration must perform no graph or remote I/O and must not
+ * initialize a signer.
+ */
+
+export const SHARE_LINK_MAINTENANCE_ENV = {
+    NAMESPACE: 'SHARE_LINK_MAINTENANCE_NAMESPACE',
+    ORIGIN: 'SHARE_LINK_MAINTENANCE_ORIGIN',
+    AUDIENCE: 'SHARE_LINK_MAINTENANCE_AUDIENCE',
+    ALLOW_INSECURE_LOOPBACK: 'SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK',
+    CLAIMANT: 'SHARE_LINK_MAINTENANCE_CLAIMANT',
+    RECOVERY_LIMIT: 'SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT',
+    CLEANUP_LIMIT: 'SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT',
+    RECEIPT_PRUNE_LIMIT: 'SHARE_LINK_MAINTENANCE_RECEIPT_PRUNE_LIMIT',
+    LEASE_MS: 'SHARE_LINK_MAINTENANCE_LEASE_MS',
+    CLAIM_MS: 'SHARE_LINK_MAINTENANCE_CLAIM_MS',
+    BUDGET_MS: 'SHARE_LINK_MAINTENANCE_BUDGET_MS',
+    INTERVAL_MS: 'SHARE_LINK_MAINTENANCE_INTERVAL_MS',
+    REQUEST_TIMEOUT_MS: 'SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS',
+    FINALIZE_RESERVE_MS: 'SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS',
+    GRAPH_TIMEOUT_MS: 'SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS',
+} as const;
+
+export const SHARE_LINK_MAINTENANCE_DEFAULTS = Object.freeze({
+    claimant: 'brain-share-link-maintenance',
+    recoveryLimit: SHARE_LINK_RECOVERY_DEFAULT_BATCH,
+    cleanupLimit: SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    receiptPruneLimit: 200,
+    leaseMs: SHARE_LINK_DEFAULT_LEASE_MS,
+    claimMs: SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS,
+    budgetMs: 60_000,
+    intervalMs: 300_000,
+    requestTimeoutMs: 10_000,
+    finalizeReserveMs: 5_000,
+    graphTimeoutMs: 15_000,
+});
+
+export const SHARE_LINK_MAINTENANCE_INVALID_CATEGORY =
+    'share_link_maintenance_configuration_invalid' as const;
+
+/**
+ * Transport/service-client portion of the share-content configuration.
+ *
+ * Owner/public APIs and maintenance use the same validated namespace, origin,
+ * and audience. No backend rollout flag is required.
+ */
+export type ShareLinkServiceTransportConfig = {
+    namespace: string;
+    origin: string;
+    audience: string;
+    allowInsecureLoopback: boolean;
+};
+
+export type ShareLinkServiceTransportConfigResolution =
+    { status: 'enabled'; config: ShareLinkServiceTransportConfig } | { status: 'invalid' };
+
+/** Whether any required service wiring has been supplied (empty deployment defaults are absent). */
+export const hasShareLinkServiceTransportConfig = (source: Record<string, unknown>): boolean =>
+    [
+        SHARE_LINK_MAINTENANCE_ENV.NAMESPACE,
+        SHARE_LINK_MAINTENANCE_ENV.ORIGIN,
+        SHARE_LINK_MAINTENANCE_ENV.AUDIENCE,
+    ].some(key => source[key] !== undefined && source[key] !== null && source[key] !== '');
+
+/**
+ * Validate service-client transport fields without echoing values or exceptions.
+ */
+export const resolveShareLinkServiceTransportConfig = (
+    raw: unknown
+): ShareLinkServiceTransportConfigResolution => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { status: 'invalid' };
+    }
+
+    const source = raw as Record<string, unknown>;
+    const allowInsecureLoopback = parseDeliberateBoolean(
+        source[SHARE_LINK_MAINTENANCE_ENV.ALLOW_INSECURE_LOOPBACK]
+    );
+    if (allowInsecureLoopback === null) return { status: 'invalid' };
+    const insecureLoopbackAllowed = allowInsecureLoopback === true;
+
+    const origin = validateShareContentOrigin(
+        source[SHARE_LINK_MAINTENANCE_ENV.ORIGIN],
+        insecureLoopbackAllowed
+    );
+    if (!origin.ok) return { status: 'invalid' };
+
+    const namespace = source[SHARE_LINK_MAINTENANCE_ENV.NAMESPACE];
+    if (!isOpaqueIdentifier(namespace)) return { status: 'invalid' };
+
+    const audience = source[SHARE_LINK_MAINTENANCE_ENV.AUDIENCE];
+    if (typeof audience !== 'string' || !audience.startsWith('did:')) {
+        return { status: 'invalid' };
+    }
+
+    return {
+        status: 'enabled',
+        config: {
+            namespace,
+            origin: origin.origin,
+            audience,
+            allowInsecureLoopback: insecureLoopbackAllowed,
+        },
+    };
+};
+
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+
+const isOpaqueIdentifier = (value: unknown, maxLength = 128): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= maxLength &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+const MISSING = Symbol('missing');
+
+/** Deliberate boolean parse: only booleans and the exact strings true/false. */
+const parseDeliberateBoolean = (value: unknown): boolean | typeof MISSING | null => {
+    if (value === undefined || value === null || value === '') return MISSING;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true') return true;
+        if (normalized === 'false') return false;
+    }
+
+    return null;
+};
+
+type BoundedIntegerOptions = { minimum: number; maximum: number; fallback: number };
+
+const parseBoundedInteger = (
+    value: unknown,
+    options: BoundedIntegerOptions
+): number | typeof MISSING | null => {
+    if (value === undefined || value === null || value === '') return MISSING;
+
+    let parsed: number;
+    if (typeof value === 'number') parsed = value;
+    else if (typeof value === 'string' && /^[0-9]+$/.test(value.trim()))
+        parsed = Number(value.trim());
+    else return null;
+
+    if (!Number.isSafeInteger(parsed) || parsed < options.minimum || parsed > options.maximum)
+        return null;
+
+    return parsed;
+};
+
+const invalid = (): ShareLinkMaintenanceConfigResolution => ({
+    status: 'invalid',
+    category: SHARE_LINK_MAINTENANCE_INVALID_CATEGORY,
+});
+
+/**
+ * Resolve maintenance configuration from a raw record (typically `process.env`).
+ * Never throws and never echoes a value.
+ */
+export const resolveShareLinkMaintenanceConfig = (
+    raw: unknown
+): ShareLinkMaintenanceConfigResolution => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return invalid();
+
+    const source = raw as Record<string, unknown>;
+    if (!hasShareLinkServiceTransportConfig(source)) return { status: 'disabled' };
+
+    const transport = resolveShareLinkServiceTransportConfig(source);
+    if (transport.status !== 'enabled') return invalid();
+
+    const { namespace, origin, audience, allowInsecureLoopback } = transport.config;
+
+    const claimantValue = source[SHARE_LINK_MAINTENANCE_ENV.CLAIMANT];
+    const claimant =
+        claimantValue === undefined || claimantValue === ''
+            ? SHARE_LINK_MAINTENANCE_DEFAULTS.claimant
+            : claimantValue;
+    if (!isOpaqueIdentifier(claimant)) return invalid();
+
+    const numericFields: Array<[string, BoundedIntegerOptions]> = [
+        [
+            SHARE_LINK_MAINTENANCE_ENV.RECOVERY_LIMIT,
+            {
+                minimum: 1,
+                maximum: SHARE_LINK_RECOVERY_MAX_BATCH,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.recoveryLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.CLEANUP_LIMIT,
+            {
+                minimum: 1,
+                maximum: SHARE_LINK_CLEANUP_MAX_BATCH,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.cleanupLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.RECEIPT_PRUNE_LIMIT,
+            {
+                minimum: 1,
+                maximum: 1_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.receiptPruneLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.LEASE_MS,
+            {
+                minimum: 1_000,
+                maximum: 30 * 60 * 1000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.leaseMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.CLAIM_MS,
+            {
+                minimum: SHARE_LINK_CLEANUP_MIN_CLAIM_MS,
+                maximum: SHARE_LINK_CLEANUP_MAX_CLAIM_MS,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.claimMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.BUDGET_MS,
+            {
+                minimum: 1_000,
+                maximum: 240_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.budgetMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.INTERVAL_MS,
+            {
+                minimum: 1_000,
+                maximum: 60 * 60 * 1000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.intervalMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.REQUEST_TIMEOUT_MS,
+            {
+                minimum: 100,
+                maximum: 30_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.requestTimeoutMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.FINALIZE_RESERVE_MS,
+            {
+                minimum: 100,
+                maximum: 120_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.finalizeReserveMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.GRAPH_TIMEOUT_MS,
+            {
+                minimum: 100,
+                maximum: 120_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.graphTimeoutMs,
+            },
+        ],
+    ];
+
+    const resolved: Record<string, number> = {};
+    for (const [key, options] of numericFields) {
+        const parsed = parseBoundedInteger(source[key], options);
+        if (parsed === null) return invalid();
+        resolved[key] = parsed === MISSING ? options.fallback : parsed;
+    }
+
+    const budgetMs = resolved[SHARE_LINK_MAINTENANCE_ENV.BUDGET_MS] as number;
+    const finalizeReserveMs = resolved[SHARE_LINK_MAINTENANCE_ENV.FINALIZE_RESERVE_MS] as number;
+    if (finalizeReserveMs >= budgetMs) return invalid();
+
+    const config: ShareLinkMaintenanceConfig = {
+        namespace,
+        origin,
+        audience,
+        allowInsecureLoopback,
+        claimant,
+        recoveryLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.RECOVERY_LIMIT] as number,
+        cleanupLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.CLEANUP_LIMIT] as number,
+        receiptPruneLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.RECEIPT_PRUNE_LIMIT] as number,
+        leaseMs: resolved[SHARE_LINK_MAINTENANCE_ENV.LEASE_MS] as number,
+        claimMs: resolved[SHARE_LINK_MAINTENANCE_ENV.CLAIM_MS] as number,
+        budgetMs,
+        intervalMs: resolved[SHARE_LINK_MAINTENANCE_ENV.INTERVAL_MS] as number,
+        requestTimeoutMs: resolved[SHARE_LINK_MAINTENANCE_ENV.REQUEST_TIMEOUT_MS] as number,
+        finalizeReserveMs,
+        graphTimeoutMs: resolved[SHARE_LINK_MAINTENANCE_ENV.GRAPH_TIMEOUT_MS] as number,
+    };
+
+    return { status: 'enabled', config };
+};

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

@@ -0,0 +1,24 @@
+export * from './types';
+export {
+    SHARE_LINK_MAINTENANCE_DEFAULTS,
+    SHARE_LINK_MAINTENANCE_ENV,
+    SHARE_LINK_MAINTENANCE_INVALID_CATEGORY,
+    resolveShareLinkMaintenanceConfig,
+} from './config';
+export { createMaintenancePassBudget, type MaintenancePassBudget } from './budget';
+export {
+    createConsoleMaintenanceLogger,
+    safeLogMaintenance,
+    toMaintenanceLogEvent,
+} from './telemetry';
+export { runShareLinkMaintenancePass, type ShareLinkMaintenanceRunnerDependencies } from './runner';
+export {
+    createShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceSchedulerDependencies,
+} from './scheduler';
+export {
+    createShareLinkMaintenanceRuntime,
+    type CreateShareLinkMaintenanceRuntimeOptions,
+    type ShareLinkMaintenanceRuntime,
+} from './runtime';