@learncard/learn-cloud-service 2.5.34 → 2.5.36

package/src/models/ShareContent.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import {
+    JWEValidator,
+    MAX_SHARE_CIPHERTEXT_BYTES,
+    MAX_SHARE_RECOVERY_JWE_BYTES,
+    ShareEnvelopeValidator,
+    ShareLinkIdValidator,
+    ShareOwnerRecoveryValidator,
+    decodedBase64UrlByteLength,
+    type ShareEnvelope,
+    type ShareOwnerRecovery,
+    utf8ByteLength,
+} from '@learncard/types';
+
+import {
+    computeShareContentRequestHash,
+    isOpaqueIdentifier,
+    isSafeContentVersion,
+} from '@helpers/share-content-auth/canonical';
+
+/**
+ * LC-2187 dedicated LearnCloud `share_content` collection.
+ *
+ * This module defines the *storage* grammar for an immutable encrypted share
+ * object plus its permanent deletion tombstone. It is deliberately separate
+ * from the recipient manifest owners in `@learncard/types`: it never models
+ * plaintext, source URIs or keys, only opaque bindings and the already-encrypted
+ * envelope/recovery bytes.
+ *
+ * Security invariants encoded here:
+ * - The immutable identity is `(namespace, objectId)`. Every other binding
+ *   (`ownerProfileId`, `shareId`, `contentVersion`, `operationId`) is part of
+ *   the exact tuple and must match on every read/mutation.
+ * - `contentHash` is *derived* by {@link computeShareContentHash} over the full
+ *   validated immutable record (all bindings plus the ciphertext envelope and
+ *   the owner-encrypted recovery). A caller-supplied hash is never accepted, so
+ *   a forged hash cannot mask divergent bytes.
+ * - The recovery projection is deliberately owner-only at the route layer. The
+ *   stored recovery JWE is strict at the top level: unknown metadata/URL fields
+ *   are rejected, not persisted.
+ * - Bound sizes: decoded ciphertext (tag included) is at most
+ *   {@link MAX_SHARE_CIPHERTEXT_BYTES}; the serialized recovery JWE is at most
+ *   {@link MAX_SHARE_RECOVERY_JWE_BYTES}.
+ */
+
+/** MongoDB collection name for immutable encrypted share content. */
+export const SHARE_CONTENT_COLLECTION = 'share_content';
+
+const SHARE_CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+
+/** Opaque, URL-safe binding identifier. Deliberately not a UUID-only check. */
+const opaqueIdentifier = (label: string, maxLength = 128) =>
+    z.string().refine(value => isOpaqueIdentifier(value, maxLength), {
+        message: `${label} must be an opaque URL-safe identifier of 1..${maxLength} characters`,
+    });
+
+/** Service/network/tenant namespace. Opaque; not a URL or host. */
+export const ShareContentNamespaceValidator = opaqueIdentifier('namespace');
+export type ShareContentNamespace = z.infer<typeof ShareContentNamespaceValidator>;
+
+/** Opaque owner profile id (existing ids are opaque strings, not necessarily UUIDs). */
+export const ShareContentOwnerProfileIdValidator = opaqueIdentifier('ownerProfileId');
+export type ShareContentOwnerProfileId = z.infer<typeof ShareContentOwnerProfileIdValidator>;
+
+/** Opaque immutable object id reserved by Brain. Never a URI. */
+export const ShareContentObjectIdValidator = opaqueIdentifier('objectId');
+export type ShareContentObjectId = z.infer<typeof ShareContentObjectIdValidator>;
+
+/** Opaque operation/idempotency id that owns the immutable object. */
+export const ShareContentOperationIdValidator = opaqueIdentifier('operationId');
+export type ShareContentOperationId = z.infer<typeof ShareContentOperationIdValidator>;
+
+/** Positive safe-integer content version (`1..2^31-1`). */
+export const ShareContentVersionValidator = z
+    .number()
+    .refine(isSafeContentVersion, { message: 'contentVersion must be a safe integer >= 1' });
+export type ShareContentContentVersion = z.infer<typeof ShareContentVersionValidator>;
+
+/** Lowercase hex SHA-256 of the derived immutable record. */
+export const ShareContentHashValidator = z
+    .string()
+    .regex(SHARE_CONTENT_HASH_PATTERN, { message: 'contentHash must be lowercase hex sha256' });
+export type ShareContentHash = z.infer<typeof ShareContentHashValidator>;
+
+/**
+ * Strict top-level owner recovery JWE. Wraps the shared
+ * {@link ShareOwnerRecoveryValidator} (which enforces the serialized 64 KiB cap)
+ * and additionally rejects unknown top-level keys so arbitrary metadata or URLs
+ * can never be persisted alongside the opaque recovery.
+ */
+export const ShareContentOwnerRecoveryValidator = JWEValidator.strict().refine(
+    value => ShareOwnerRecoveryValidator.safeParse(value).success,
+    { message: 'must be a valid bounded owner-encrypted recovery JWE' }
+);
+export type ShareContentOwnerRecovery = z.infer<typeof ShareContentOwnerRecoveryValidator>;
+
+/**
+ * The exact, immutable object binding. The repository applies this to every
+ * operation; a mutation of any single field fails closed.
+ */
+export const ShareContentObjectBindingValidator = z
+    .object({
+        namespace: ShareContentNamespaceValidator,
+        ownerProfileId: ShareContentOwnerProfileIdValidator,
+        shareId: ShareLinkIdValidator,
+        contentVersion: ShareContentVersionValidator,
+        objectId: ShareContentObjectIdValidator,
+        operationId: ShareContentOperationIdValidator,
+    })
+    .strict();
+export type ShareContentObjectBinding = z.infer<typeof ShareContentObjectBindingValidator>;
+
+/**
+ * A create-only write. `contentHash` is intentionally absent: the repository
+ * derives it, so a caller cannot supply (and therefore cannot forge) it.
+ */
+export const ShareContentPutInputValidator = ShareContentObjectBindingValidator.extend({
+    envelope: ShareEnvelopeValidator,
+    ownerEncryptedRecovery: ShareContentOwnerRecoveryValidator,
+}).strict();
+export type ShareContentPutInput = z.infer<typeof ShareContentPutInputValidator>;
+
+/**
+ * Derive the content hash over the complete immutable record: all bindings plus
+ * the validated ciphertext envelope and the owner-encrypted recovery. The C1
+ * canonical serializer makes the result deterministic and rejects unsupported
+ * values instead of coercing them.
+ */
+export const computeShareContentHash = (input: ShareContentPutInput): string =>
+    computeShareContentRequestHash({
+        namespace: input.namespace,
+        ownerProfileId: input.ownerProfileId,
+        shareId: input.shareId,
+        contentVersion: input.contentVersion,
+        objectId: input.objectId,
+        operationId: input.operationId,
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+    });
+
+/** Hash known before Brain allocates object/operation IDs; reservation binding. */
+export const computeSharePayloadHash = (
+    input: Pick<ShareContentPutInput, 'envelope' | 'ownerEncryptedRecovery'>
+): string =>
+    computeShareContentRequestHash({
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+    });
+
+/**
+ * Measure the encoded payload for reconciliation/stats. Assumes `input` already
+ * passed {@link ShareContentPutInputValidator}.
+ */
+export const measureShareContentPayload = (
+    input: Pick<ShareContentPutInput, 'envelope' | 'ownerEncryptedRecovery'>
+): { ciphertextBytes: number; recoveryBytes: number } => {
+    const ciphertextBytes = decodedBase64UrlByteLength(input.envelope.ct);
+
+    if (ciphertextBytes === null) {
+        throw new Error('validated envelope ciphertext must be canonical base64url');
+    }
+
+    return {
+        ciphertextBytes,
+        recoveryBytes: utf8ByteLength(JSON.stringify(input.ownerEncryptedRecovery)),
+    };
+};
+
+/** Immutable active document. */
+export const MongoShareContentActiveValidator = ShareContentObjectBindingValidator.extend({
+    kind: z.literal('active'),
+    contentHash: ShareContentHashValidator,
+    payloadHash: ShareContentHashValidator,
+    envelope: ShareEnvelopeValidator,
+    ownerEncryptedRecovery: ShareContentOwnerRecoveryValidator,
+    ciphertextBytes: z.number().int().min(16).max(MAX_SHARE_CIPHERTEXT_BYTES),
+    recoveryBytes: z.number().int().min(1).max(MAX_SHARE_RECOVERY_JWE_BYTES),
+    createdAt: z.date(),
+}).strict();
+export type MongoShareContentActive = z.infer<typeof MongoShareContentActiveValidator>;
+
+/**
+ * Permanent deletion tombstone. Retains the binding tuple and, where known, the
+ * derived hash; never retains ciphertext or recovery. A tombstone blocks every
+ * later put for the same `(namespace, objectId)` identity.
+ */
+export const MongoShareContentTombstoneValidator = ShareContentObjectBindingValidator.extend({
+    kind: z.literal('tombstone'),
+    contentHash: ShareContentHashValidator.optional(),
+    deletedAt: z.date(),
+}).strict();
+export type MongoShareContentTombstone = z.infer<typeof MongoShareContentTombstoneValidator>;
+
+/** Stored document union. */
+export type MongoShareContentDocument = MongoShareContentActive | MongoShareContentTombstone;
+
+/** Raw ciphertext envelope carried by an active object. */
+export type { ShareEnvelope, ShareOwnerRecovery };

package/src/models/index.ts

@@ -1,4 +1,5 @@
 export * from './Credential';
 export * from './CredentialRecord';
 export * from './CustomDocument';
+export * from './ShareContent';
 export * from './User';

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';