@learncard/learn-cloud-service 2.5.34 → 2.5.35

package/src/share-content/config.ts

@@ -0,0 +1,199 @@
+import {
+    isShareContentTrustConfigActive,
+    resolveShareContentTrustConfig,
+    type ShareContentTrustConfig,
+} from '@helpers/share-content-auth';
+
+import { SHARE_CONTENT_MAX_REQUEST_BYTES, type ShareContentPluginOptions } from './types';
+
+/**
+ * Fail-closed runtime configuration for the LC-2187 service-only routes.
+ *
+ * There is deliberately no offline or development bypass: when the configuration
+ * is absent, disabled, incomplete or internally inconsistent the resolver
+ * returns `disabled`/`invalid` and the routes stay unregistered. Namespace
+ * authorization is an explicit per-service binding so a valid service token can
+ * never name an arbitrary namespace.
+ */
+
+export type ShareContentNamespacePolicy = {
+    /** True only when this exact allowlisted service may use this exact namespace. */
+    isAllowed: (serviceDid: string, namespace: string) => boolean;
+    /** Configured namespaces for one service (diagnostics/tests only). */
+    allowedNamespacesFor: (serviceDid: string) => readonly string[];
+};
+
+export type ResolvedShareContentConfig =
+    | { status: 'disabled' }
+    | { status: 'invalid'; errors: readonly string[] }
+    | {
+          status: 'enabled';
+          trustConfig: ShareContentTrustConfig;
+          namespacePolicy: ShareContentNamespacePolicy;
+      };
+
+const toStringList = (value: unknown): string[] | null => {
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map(part => part.trim())
+            .filter(part => part.length > 0);
+    }
+
+    if (Array.isArray(value)) {
+        if (!value.every(item => typeof item === 'string')) return null;
+
+        return value.map(item => item.trim()).filter(item => item.length > 0);
+    }
+
+    return null;
+};
+
+/**
+ * Parse the per-service namespace bindings. Accepts an object map, or a JSON
+ * string of one (deployment manifests cannot express nested maps). Every entry
+ * must be a non-empty list of non-empty namespace identifiers.
+ */
+export const parseShareContentNamespaceBindings = (
+    value: unknown
+): Map<string, readonly string[]> | null => {
+    let source: unknown = value;
+
+    if (typeof value === 'string') {
+        try {
+            source = JSON.parse(value);
+        } catch {
+            return null;
+        }
+    }
+
+    if (typeof source !== 'object' || source === null || Array.isArray(source)) return null;
+
+    const bindings = new Map<string, readonly string[]>();
+
+    for (const [serviceDid, namespacesValue] of Object.entries(source as Record<string, unknown>)) {
+        if (serviceDid.trim().length === 0) return null;
+
+        const namespaces = toStringList(namespacesValue);
+
+        if (!namespaces || namespaces.length === 0) return null;
+
+        bindings.set(serviceDid.trim(), namespaces);
+    }
+
+    return bindings.size > 0 ? bindings : null;
+};
+
+const buildNamespacePolicy = (
+    bindings: Map<string, readonly string[]>
+): ShareContentNamespacePolicy => {
+    const frozen = new Map<string, readonly string[]>();
+
+    for (const [serviceDid, namespaces] of bindings) {
+        frozen.set(serviceDid, Object.freeze([...namespaces]));
+    }
+
+    return {
+        isAllowed: (serviceDid, namespace) => frozen.get(serviceDid)?.includes(namespace) ?? false,
+        allowedNamespacesFor: serviceDid => frozen.get(serviceDid) ?? [],
+    };
+};
+
+/**
+ * Resolve the explicit configuration. An empty allowlist, empty verification
+ * methods, or missing namespace bindings all fail closed. A
+ * partially supplied configuration is reported as `invalid`; the caller
+ * must then refuse to register routes (startup fails explicitly rather than
+ * silently widening access).
+ */
+export const resolveShareContentConfig = (raw: unknown): ResolvedShareContentConfig => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { status: 'disabled' };
+    }
+
+    const source = raw as Record<string, unknown>;
+
+    if (
+        !['audience', 'serviceDids', 'verificationMethods', 'namespaceBindings'].some(
+            key => source[key] !== undefined && source[key] !== null && source[key] !== ''
+        )
+    )
+        return { status: 'disabled' };
+
+    const errors: string[] = [];
+
+    const audience = typeof source.audience === 'string' ? source.audience.trim() : '';
+    if (audience.length === 0) errors.push('audience is required');
+
+    const serviceDids = toStringList(source.serviceDids) ?? [];
+    if (serviceDids.length === 0) errors.push('serviceDids must list at least one service DID');
+
+    const verificationMethods = toStringList(source.verificationMethods) ?? [];
+    if (verificationMethods.length === 0) {
+        errors.push('verificationMethods must list at least one exact verification method');
+    }
+
+    const bindings = parseShareContentNamespaceBindings(source.namespaceBindings);
+    if (!bindings) {
+        errors.push('namespaceBindings must map every service DID to at least one namespace');
+    }
+
+    if (bindings) {
+        for (const serviceDid of serviceDids) {
+            if (!bindings.has(serviceDid)) {
+                errors.push(`namespaceBindings is missing an entry for ${serviceDid}`);
+            }
+        }
+
+        for (const serviceDid of bindings.keys()) {
+            if (!serviceDids.includes(serviceDid)) {
+                errors.push(`namespaceBindings references a non-allowlisted service ${serviceDid}`);
+            }
+        }
+    }
+
+    if (errors.length > 0) return { status: 'invalid', errors };
+
+    // Reuse the C1 resolver for the cryptographic trust config. Passing a value
+    // that C1 would silently disable is an explicit invalid configuration here.
+    const trustConfig = resolveShareContentTrustConfig({ ...source, enabled: true });
+
+    if (!isShareContentTrustConfigActive(trustConfig)) {
+        return {
+            status: 'invalid',
+            errors: ['resolved trust configuration is not active'],
+        };
+    }
+
+    return {
+        status: 'enabled',
+        trustConfig,
+        namespacePolicy: buildNamespacePolicy(bindings as Map<string, readonly string[]>),
+    };
+};
+
+/**
+ * Build the exact raw object the resolver expects from an already-parsed
+ * LearnCloud environment. Kept tiny so entrypoints cannot drift from each other.
+ */
+export const getShareContentRawConfig = (environment: {
+    SHARE_CONTENT_AUDIENCE?: string;
+    SHARE_CONTENT_SERVICE_DIDS?: string;
+    SHARE_CONTENT_VERIFICATION_METHODS?: string;
+    SHARE_CONTENT_NAMESPACE_BINDINGS?: string;
+}): Record<string, unknown> => ({
+    audience: environment.SHARE_CONTENT_AUDIENCE,
+    serviceDids: environment.SHARE_CONTENT_SERVICE_DIDS,
+    verificationMethods: environment.SHARE_CONTENT_VERIFICATION_METHODS,
+    namespaceBindings: environment.SHARE_CONTENT_NAMESPACE_BINDINGS,
+});
+
+/** Build the plugin options from a resolved, enabled configuration. */
+export const toShareContentPluginOptions = (
+    config: Extract<ResolvedShareContentConfig, { status: 'enabled' }>,
+    dependencies: Pick<ShareContentPluginOptions, 'verifier' | 'repository'>
+): ShareContentPluginOptions => ({
+    ...dependencies,
+    namespacePolicy: config.namespacePolicy,
+    maxRequestBytes: SHARE_CONTENT_MAX_REQUEST_BYTES,
+});

package/src/share-content/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './config';
+export * from './plugin';
+export * from './runtime';
+export * from './production';

package/src/share-content/plugin.ts

@@ -0,0 +1,317 @@
+import type { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+import {
+    MAX_SHARE_CIPHERTEXT_BYTES,
+    MAX_SHARE_RECOVERY_JWE_BYTES,
+    decodedBase64UrlByteLength,
+    utf8ByteLength,
+} from '@learncard/types';
+
+import {
+    ShareContentObjectBindingValidator,
+    ShareContentPutInputValidator,
+    type ShareContentObjectBinding,
+} from '@models';
+import { computeShareContentRequestHash, isPlainObject } from '@helpers/share-content-auth';
+
+import {
+    SHARE_CONTENT_MAX_REQUEST_BYTES,
+    type ShareContentErrorCode,
+    type ShareContentPluginOptions,
+    type ShareContentRouteOperation,
+} from './types';
+
+/**
+ * Fixed LC-2187 service HTTP contract over the reviewed C1 verifier and C2
+ * repository.
+ *
+ * Invariants enforced here:
+ * - The operation is selected by the server route, never by the body; a body
+ *   carrying an `op` field fails the strict tuple schema.
+ * - The request hash is the C1 canonical SHA-256 of the entire validated request
+ *   body (including the opaque envelope and recovery on `put`), bound to the
+ *   token claims. A caller-supplied hash is never accepted as authority.
+ * - Authentication precedes every repository operation. Parsing is not
+ *   authentication.
+ * - The repository result is mapped to a small fixed error vocabulary; raw
+ *   errors, tokens, bodies and ciphertext are never returned or logged.
+ * - Exact-object `get` never reads recovery; `readRecovery` is a separate route
+ *   that requires its own signed intent.
+ */
+
+const BEARER_AUTHORIZATION_RE = /^Bearer ([A-Za-z0-9._-]+)$/;
+
+const sendError = (reply: FastifyReply, status: number, error: ShareContentErrorCode) =>
+    reply.status(status).send({ ok: false, error });
+
+type ExtractedToken = { ok: true; token: string } | { ok: false };
+
+/**
+ * Bound and extract the bearer token before any parsing or verification. The
+ * accepted header is deliberately tiny and the C1 config's `maxTokenBytes` is
+ * the hard ceiling, so a caller cannot widen the accepted transport size.
+ */
+const extractBearerToken = (header: unknown, maxTokenBytes: number): ExtractedToken => {
+    if (typeof header !== 'string') return { ok: false };
+    if (header.length > maxTokenBytes + 'Bearer '.length) return { ok: false };
+    if (Buffer.byteLength(header, 'utf8') > maxTokenBytes + 'Bearer '.length) return { ok: false };
+
+    const match = BEARER_AUTHORIZATION_RE.exec(header);
+
+    if (!match) return { ok: false };
+
+    return { ok: true, token: match[1] as string };
+};
+
+/**
+ * Fast, allocation-light size check that runs before strict schema validation so
+ * an over-limit decoded ciphertext or serialized recovery is reported as a size
+ * failure (413) rather than a generic shape failure (400). Legacy malformed
+ * spellings still fall through to the schema.
+ */
+const exceedsPayloadBounds = (body: unknown): boolean => {
+    if (!isPlainObject(body)) return false;
+
+    const envelope = body.envelope;
+
+    if (isPlainObject(envelope) && typeof envelope.ct === 'string') {
+        if (envelope.ct.length > Math.ceil((MAX_SHARE_CIPHERTEXT_BYTES * 4) / 3)) return true;
+
+        const decodedBytes = decodedBase64UrlByteLength(envelope.ct);
+
+        if (decodedBytes !== null && decodedBytes > MAX_SHARE_CIPHERTEXT_BYTES) return true;
+    }
+
+    const recovery = body.ownerEncryptedRecovery;
+
+    if (isPlainObject(recovery)) {
+        if (utf8ByteLength(JSON.stringify(recovery)) > MAX_SHARE_RECOVERY_JWE_BYTES) return true;
+    }
+
+    return false;
+};
+
+const mapRepositoryError = (reply: FastifyReply, error: string | undefined) => {
+    switch (error) {
+        case 'INVALID_INPUT':
+            return sendError(reply, 400, 'INVALID_INPUT');
+        case 'NOT_FOUND':
+            return sendError(reply, 404, 'NOT_FOUND');
+        case 'TOMBSTONED':
+        case 'BINDING_MISMATCH':
+        case 'CONFLICT':
+            return sendError(reply, 409, 'CONFLICT');
+        case 'STORE_ERROR':
+        default:
+            return sendError(reply, 503, 'UNAVAILABLE');
+    }
+};
+
+/**
+ * Verify authorization and the per-service namespace policy. Returns `true` only
+ * when the caller may proceed to the repository. Every failure is a generic,
+ * non-distinguishing rejection; a dependency outage (unavailable replay store)
+ * is reported as `UNAVAILABLE` and still never reaches the repository.
+ */
+const authorize = async (
+    operation: ShareContentRouteOperation,
+    binding: ShareContentObjectBinding,
+    validatedBody: unknown,
+    authorizationHeader: unknown,
+    options: ShareContentPluginOptions,
+    reply: FastifyReply
+): Promise<boolean> => {
+    const token = extractBearerToken(authorizationHeader, options.verifier.config.maxTokenBytes);
+
+    if (!token.ok) {
+        sendError(reply, 401, 'UNAUTHORIZED');
+
+        return false;
+    }
+
+    const requestHash = computeShareContentRequestHash(validatedBody);
+
+    const result = await options.verifier.authorize(
+        {
+            namespace: binding.namespace,
+            op: operation,
+            shareId: binding.shareId,
+            contentVersion: binding.contentVersion,
+            ownerProfileId: binding.ownerProfileId,
+            objectId: binding.objectId,
+            operationId: binding.operationId,
+            requestHash,
+        },
+        token.token
+    );
+
+    if (!result.ok) {
+        if (result.reason === 'REPLAY_STORE_UNAVAILABLE') {
+            sendError(reply, 503, 'UNAVAILABLE');
+        } else {
+            sendError(reply, 401, 'UNAUTHORIZED');
+        }
+
+        return false;
+    }
+
+    if (!options.namespacePolicy.isAllowed(result.context.signerDid, binding.namespace)) {
+        sendError(reply, 401, 'UNAUTHORIZED');
+
+        return false;
+    }
+
+    return true;
+};
+
+const toBinding = (body: ShareContentObjectBinding): ShareContentObjectBinding => ({
+    namespace: body.namespace,
+    ownerProfileId: body.ownerProfileId,
+    shareId: body.shareId,
+    contentVersion: body.contentVersion,
+    objectId: body.objectId,
+    operationId: body.operationId,
+});
+
+const handlePut = async (
+    request: FastifyRequest,
+    reply: FastifyReply,
+    options: ShareContentPluginOptions
+) => {
+    if (exceedsPayloadBounds(request.body)) return sendError(reply, 413, 'PAYLOAD_TOO_LARGE');
+
+    const parsed = ShareContentPutInputValidator.safeParse(request.body);
+
+    if (!parsed.success) return sendError(reply, 400, 'INVALID_INPUT');
+
+    const body = parsed.data;
+
+    if (
+        !(await authorize(
+            'put',
+            toBinding(body),
+            body,
+            request.headers.authorization,
+            options,
+            reply
+        ))
+    ) {
+        return reply;
+    }
+
+    try {
+        const result = await options.repository.put(body);
+
+        if (!result.ok) return mapRepositoryError(reply, result.error);
+
+        return reply.status(200).send({ ok: true, value: result.value });
+    } catch {
+        return sendError(reply, 503, 'UNAVAILABLE');
+    }
+};
+
+const handleExactObject = async (
+    operation: Exclude<ShareContentRouteOperation, 'put'>,
+    request: FastifyRequest,
+    reply: FastifyReply,
+    options: ShareContentPluginOptions
+) => {
+    const parsed = ShareContentObjectBindingValidator.safeParse(request.body);
+
+    if (!parsed.success) return sendError(reply, 400, 'INVALID_INPUT');
+
+    const binding = parsed.data;
+
+    if (
+        !(await authorize(
+            operation,
+            binding,
+            binding,
+            request.headers.authorization,
+            options,
+            reply
+        ))
+    ) {
+        return reply;
+    }
+
+    try {
+        const result =
+            operation === 'get'
+                ? await options.repository.getContent(binding)
+                : operation === 'stat'
+                  ? await options.repository.stat(binding)
+                  : operation === 'delete'
+                    ? await options.repository.delete(binding)
+                    : await options.repository.getRecovery(binding);
+
+        if (!result.ok) return mapRepositoryError(reply, result.error);
+
+        return reply.status(200).send({ ok: true, value: result.value });
+    } catch {
+        return sendError(reply, 503, 'UNAVAILABLE');
+    }
+};
+
+/**
+ * The dedicated Fastify plugin. It reads no environment and opens no
+ * connections: the startup wrapper injects the verifier, the initialized
+ * repository and the namespace policy, and only registers the plugin when the
+ * configuration is valid and enabled.
+ */
+export const shareContentFastifyPlugin: FastifyPluginAsync<ShareContentPluginOptions> = async (
+    fastify: FastifyInstance,
+    options: ShareContentPluginOptions
+) => {
+    const bodyLimit = Math.max(
+        1,
+        Math.min(
+            options.maxRequestBytes ?? SHARE_CONTENT_MAX_REQUEST_BYTES,
+            SHARE_CONTENT_MAX_REQUEST_BYTES
+        )
+    );
+
+    fastify.addHook('onSend', async (_request, reply) => {
+        reply.header('Cache-Control', 'no-store');
+    });
+
+    // Route-scoped sanitized error handling. Parser errors (too large, malformed
+    // JSON, unsupported content type) never leak a raw message, and unknown
+    // failures collapse to the same non-disclosing `UNAVAILABLE` shape.
+    fastify.setErrorHandler((error, _request, reply) => {
+        const code =
+            typeof error === 'object' && error !== null
+                ? (error as { code?: unknown }).code
+                : undefined;
+
+        if (code === 'FST_ERR_CTP_BODY_TOO_LARGE') {
+            return sendError(reply, 413, 'PAYLOAD_TOO_LARGE');
+        }
+
+        if (
+            code === 'FST_ERR_CTP_INVALID_MEDIA_TYPE' ||
+            code === 'FST_ERR_CTP_INVALID_JSON' ||
+            code === 'FST_ERR_CTP_INVALID_JSON_BODY' ||
+            code === 'FST_ERR_CTP_EMPTY_JSON_BODY'
+        ) {
+            return sendError(reply, 400, 'INVALID_INPUT');
+        }
+
+        return sendError(reply, 503, 'UNAVAILABLE');
+    });
+
+    fastify.post('/put', { bodyLimit }, (request, reply) => handlePut(request, reply, options));
+    fastify.post('/get', { bodyLimit }, (request, reply) =>
+        handleExactObject('get', request, reply, options)
+    );
+    fastify.post('/stat', { bodyLimit }, (request, reply) =>
+        handleExactObject('stat', request, reply, options)
+    );
+    fastify.post('/delete', { bodyLimit }, (request, reply) =>
+        handleExactObject('delete', request, reply, options)
+    );
+    fastify.post('/readRecovery', { bodyLimit }, (request, reply) =>
+        handleExactObject('readRecovery', request, reply, options)
+    );
+};
+
+export default shareContentFastifyPlugin;

package/src/share-content/production.ts

@@ -0,0 +1,107 @@
+import Redis from 'ioredis';
+
+import { environment } from '@environment';
+import {
+    createShareContentRepository,
+    getShareContentCollection,
+    type ShareContentRepository,
+} from '@accesslayer/share-content';
+import { createSetIfAbsentReplayStore, type ReplayStore } from '@helpers/share-content-auth';
+import { getEmptyLearnCard } from '@helpers/learnCard.helpers';
+
+import { getShareContentRawConfig, resolveShareContentConfig } from './config';
+import { buildShareContentRuntime, type ShareContentRuntime } from './runtime';
+
+/**
+ * Production wiring for the LC-2187 service routes. Kept separate from the pure
+ * `runtime.ts` builder so the transport logic stays testable without the
+ * environment/Mongo connection singletons.
+ *
+ * The replay store is a real ioredis `SET key 1 EX ttl NX`. There is
+ * deliberately no `cache.node` / `ioredis-mock` fallback here: an absent or
+ * unreachable Redis must fail closed, not silently accept every nonce.
+ */
+
+export type ShareContentReplayStoreHandle = {
+    store: ReplayStore;
+    close: () => Promise<void>;
+};
+
+export const createShareContentRedisReplayStore = (options: {
+    host: string;
+    port: number;
+}): ShareContentReplayStoreHandle => {
+    const client = new Redis({
+        host: options.host,
+        port: options.port,
+        connectTimeout: 5_000,
+        maxRetriesPerRequest: 1,
+        enableReadyCheck: true,
+    });
+
+    // Operational errors surface through the rejected command below. Never log
+    // the endpoint, command or payload here.
+    client.on('error', () => {});
+
+    const store = createSetIfAbsentReplayStore(async (key, ttlSeconds) => {
+        const result = await client.set(key, '1', 'EX', ttlSeconds, 'NX');
+
+        // Explicit response handling: `OK` = newly created (allowed), `null` =
+        // already present (replay), anything else is an unsafe surprise.
+        if (result === 'OK') return true;
+        if (result === null) return false;
+
+        throw new Error('unexpected Redis SET NX response');
+    });
+
+    return {
+        store,
+        close: async () => {
+            try {
+                await client.quit();
+            } catch {
+                client.disconnect();
+            }
+        },
+    };
+};
+
+export const createMongoShareContentRepository = async (): Promise<ShareContentRepository> => {
+    const { mongodb } = await import('@mongo');
+
+    return createShareContentRepository(getShareContentCollection(mongodb));
+};
+
+const requireRedisEndpoint = (): { host: string; port: number } => {
+    const { REDIS_HOST: host, REDIS_PORT: port } = environment;
+
+    if (!host || !port) {
+        throw new Error(
+            'LC-2187 share-content is enabled but REDIS_HOST/REDIS_PORT are not configured'
+        );
+    }
+
+    return { host, port };
+};
+
+export const createShareContentRuntimeFromEnvironment = async (): Promise<ShareContentRuntime> =>
+    buildShareContentRuntime(getShareContentRawConfig(environment), {
+        getLearnCard: () => getEmptyLearnCard(),
+        createReplayStore: () => createShareContentRedisReplayStore(requireRedisEndpoint()),
+        getRepository: createMongoShareContentRepository,
+    });
+
+/**
+ * Synchronous configuration gate for entrypoints that must fail fast before the
+ * first request (Lambda cold start). Reads no connections and never weakens a
+ * check.
+ */
+export const assertShareContentEnvironmentConfiguration = (): void => {
+    const resolved = resolveShareContentConfig(getShareContentRawConfig(environment));
+
+    if (resolved.status === 'invalid') {
+        throw new Error(
+            `Invalid LC-2187 share-content configuration: ${resolved.errors.join('; ')}`
+        );
+    }
+};