@learncard/learn-cloud-service 2.5.34 → 2.5.35

package/src/share-content/runtime.ts

@@ -0,0 +1,90 @@
+import type { FastifyInstance } from 'fastify';
+
+import type { ShareContentRepository } from '@accesslayer/share-content';
+import {
+    createDidkitPresentationVerifier,
+    createShareContentAuthorizationVerifier,
+    type LearnCardLike,
+    type ReplayStore,
+} from '@helpers/share-content-auth';
+
+import { resolveShareContentConfig, toShareContentPluginOptions } from './config';
+import { shareContentFastifyPlugin } from './plugin';
+import { SHARE_CONTENT_PLUGIN_PREFIX, type ShareContentPluginOptions } from './types';
+
+/**
+ * Startup wrapper for the service-only share-content routes.
+ *
+ * The builder owns the fail-closed boot order: resolve the explicit config,
+ * then (only when it is valid and enabled) open the repository, *await* its
+ * index initialization, build the DIDKit verifier and the real Redis replay
+ * store, and return injectable plugin options. A disabled configuration returns
+ * immediately and performs none of those side effects, so a disabled boot never
+ * installs indexes or opens connections.
+ */
+
+export type ShareContentRuntimeDependencies = {
+    /** Existing DIDKit verification seam; never constructed at import time. */
+    getLearnCard: () => Promise<LearnCardLike>;
+    /** Real `SET NX EX` replay store (tests may inject an explicit double). */
+    createReplayStore: () => { store: ReplayStore; close: () => Promise<void> };
+    /** Repository factory; must not connect until the enabled branch. */
+    getRepository: () => Promise<ShareContentRepository>;
+};
+
+export type EnabledShareContentRuntime = {
+    enabled: true;
+    pluginOptions: ShareContentPluginOptions;
+    /** Releases the replay-store connection. Repository pooling is owned by @mongo. */
+    close: () => Promise<void>;
+};
+
+export type ShareContentRuntime = { enabled: false } | EnabledShareContentRuntime;
+
+export const buildShareContentRuntime = async (
+    rawConfig: unknown,
+    dependencies: ShareContentRuntimeDependencies
+): Promise<ShareContentRuntime> => {
+    const resolved = resolveShareContentConfig(rawConfig);
+
+    if (resolved.status === 'disabled') return { enabled: false };
+
+    if (resolved.status === 'invalid') {
+        // Explicit startup failure: never fall back to a weaker check.
+        throw new Error(
+            `Invalid LC-2187 share-content configuration: ${resolved.errors.join('; ')}`
+        );
+    }
+
+    const repository = await dependencies.getRepository();
+
+    // Enabled boot awaits index initialization before any route can serve.
+    await repository.initialize();
+
+    const replayStore = dependencies.createReplayStore();
+
+    const verifier = createShareContentAuthorizationVerifier({
+        config: resolved.trustConfig,
+        verifyPresentation: createDidkitPresentationVerifier(dependencies.getLearnCard),
+        replayStore: replayStore.store,
+    });
+
+    return {
+        enabled: true,
+        pluginOptions: toShareContentPluginOptions(resolved, { verifier, repository }),
+        close: async () => {
+            await replayStore.close();
+        },
+    };
+};
+
+/** Register the routes under the fixed prefix on an already-built Fastify server. */
+export const registerShareContentRoutes = async (
+    fastify: FastifyInstance,
+    runtime: EnabledShareContentRuntime
+): Promise<void> => {
+    await fastify.register(shareContentFastifyPlugin, {
+        prefix: SHARE_CONTENT_PLUGIN_PREFIX,
+        ...runtime.pluginOptions,
+    });
+};

package/src/share-content/types.ts

@@ -0,0 +1,59 @@
+import type { ShareContentRepository } from '@accesslayer/share-content';
+import type { ReplayStore, ShareContentAuthorizationVerifier } from '@helpers/share-content-auth';
+
+import type { ShareContentNamespacePolicy } from './config';
+
+/**
+ * LC-2187 LearnCloud service-only share-content transport.
+ *
+ * This module is the C4 transport seam: it turns the reviewed C1 authorization
+ * verifier and the C2 immutable repository into the fixed service HTTP contract
+ * (`POST /internal/share-content/{op}`). It never redesigns the claim format,
+ * the repository state machine or the public share feature; those stay owned by
+ * their batches.
+ */
+
+/** All shared-content service routes live under this configured prefix. */
+export const SHARE_CONTENT_PLUGIN_PREFIX = '/internal/share-content';
+
+/** The exact operation is selected by the server route, never by the body. */
+export type ShareContentRouteOperation = 'put' | 'get' | 'stat' | 'delete' | 'readRecovery';
+
+/** Hard transport bound mandated by the A2 review; the Fastify default. */
+export const SHARE_CONTENT_MAX_REQUEST_BYTES = 1024 * 1024;
+
+/**
+ * Contract error statuses. Response bodies are always the generic
+ * `{ ok: false, error }` shape; internal rejection reasons are never returned.
+ */
+export const SHARE_CONTENT_ERROR_CODES = [
+    'UNAUTHORIZED',
+    'INVALID_INPUT',
+    'PAYLOAD_TOO_LARGE',
+    'NOT_FOUND',
+    'CONFLICT',
+    'UNAVAILABLE',
+] as const;
+
+export type ShareContentErrorCode = (typeof SHARE_CONTENT_ERROR_CODES)[number];
+
+export type ShareContentErrorBody = { ok: false; error: ShareContentErrorCode };
+
+/**
+ * Injected transport dependencies. The route layer only orchestrates: it
+ * validates the wire body, hashes it, asks the injected verifier to authorize,
+ * checks the configured namespace policy, then calls the repository.
+ */
+export type ShareContentPluginOptions = {
+    verifier: ShareContentAuthorizationVerifier;
+    repository: ShareContentRepository;
+    namespacePolicy: ShareContentNamespacePolicy;
+    /** Route body limit; must never exceed {@link SHARE_CONTENT_MAX_REQUEST_BYTES}. */
+    maxRequestBytes?: number;
+};
+
+/** Structural view of a Redis-like atomic replay store used by the runtime. */
+export type ShareContentReplayStoreFactory = () => {
+    store: ReplayStore;
+    close: () => Promise<void>;
+};