@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/share-content-client/client.ts

@@ -0,0 +1,440 @@
+import { randomBytes } from 'node:crypto';
+
+import { computeShareContentRequestBodyHash } from './canonical';
+import {
+    parseShareContentContentProjection,
+    parseShareContentDeleteValue,
+    parseShareContentPutValue,
+    parseShareContentRecoveryProjection,
+    parseShareContentResponseEnvelope,
+    parseShareContentStatValue,
+} from './responses';
+import {
+    MAX_SHARE_CONTENT_RETRY_BACKOFF_MS,
+    MAX_SHARE_CONTENT_TOKEN_TTL_SECONDS,
+    SHARE_CONTENT_AUTH_PURPOSE,
+    isTransientShareContentError,
+    type ShareContentAuthorizationClaims,
+    type ShareContentClient,
+    type ShareContentClientConfig,
+    type ShareContentClientErrorCode,
+    type ShareContentClientResult,
+    type ShareContentContentProjection,
+    type ShareContentDeleteValue,
+    type ShareContentEnvelope,
+    type ShareContentOperation,
+    type ShareContentPutRequest,
+    type ShareContentPutValue,
+    type ShareContentRecoveryProjection,
+    type ShareContentStatValue,
+    type ShareContentTuple,
+} from './types';
+
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+
+const isOpaqueIdentifier = (value: unknown): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= 128 &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+const isSafeVersion = (value: unknown): value is number =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= 2 ** 31 - 1;
+
+const isValidTuple = (tuple: ShareContentTuple): boolean =>
+    isOpaqueIdentifier(tuple.namespace) &&
+    isOpaqueIdentifier(tuple.ownerProfileId) &&
+    isOpaqueIdentifier(tuple.shareId) &&
+    isSafeVersion(tuple.contentVersion) &&
+    isOpaqueIdentifier(tuple.objectId) &&
+    isOpaqueIdentifier(tuple.operationId);
+
+const isValidEnvelope = (envelope: unknown): envelope is ShareContentEnvelope => {
+    if (typeof envelope !== 'object' || envelope === null || Array.isArray(envelope)) return false;
+
+    const candidate = envelope as Record<string, unknown>;
+
+    return (
+        candidate.v === 1 &&
+        candidate.alg === 'A256GCM' &&
+        typeof candidate.iv === 'string' &&
+        candidate.iv.length > 0 &&
+        typeof candidate.ct === 'string' &&
+        candidate.ct.length > 0
+    );
+};
+
+/** Fresh CSPRNG nonce for every transport attempt (never reused across retries). */
+const generateJti = (): string => randomBytes(24).toString('base64url');
+
+const buildRequestBody = (
+    request: ShareContentPutRequest | ShareContentTuple
+): Record<string, unknown> => {
+    const body: Record<string, unknown> = {
+        namespace: request.namespace,
+        ownerProfileId: request.ownerProfileId,
+        shareId: request.shareId,
+        contentVersion: request.contentVersion,
+        objectId: request.objectId,
+        operationId: request.operationId,
+    };
+
+    if ('envelope' in request && 'ownerEncryptedRecovery' in request) {
+        body.envelope = request.envelope;
+        body.ownerEncryptedRecovery = request.ownerEncryptedRecovery;
+    }
+
+    return body;
+};
+
+const buildUrl = (config: ShareContentClientConfig, op: ShareContentOperation): string =>
+    `${config.origin}/internal/share-content/${op}`;
+
+const mapStatusToError = (status: number): ShareContentClientErrorCode => {
+    switch (status) {
+        case 400:
+            return 'INVALID_INPUT';
+        case 401:
+            return 'UNAUTHORIZED';
+        case 404:
+            return 'NOT_FOUND';
+        case 409:
+            return 'CONFLICT';
+        case 413:
+            return 'PAYLOAD_TOO_LARGE';
+        case 503:
+            return 'UNAVAILABLE';
+        default:
+            return 'UNEXPECTED_STATUS';
+    }
+};
+
+const responseTupleMatches = (
+    value: {
+        namespace: string;
+        ownerProfileId: string;
+        shareId: string;
+        contentVersion: number;
+        objectId: string;
+        operationId: string;
+    },
+    tuple: ShareContentTuple
+): boolean =>
+    value.namespace === tuple.namespace &&
+    value.ownerProfileId === tuple.ownerProfileId &&
+    value.shareId === tuple.shareId &&
+    value.contentVersion === tuple.contentVersion &&
+    value.objectId === tuple.objectId &&
+    value.operationId === tuple.operationId;
+
+/** Decode the JOSE header and require it binds exactly the configured signer. */
+const validateSignedTokenHeader = (token: string, signerDid: string): boolean => {
+    if (typeof token !== 'string') return false;
+
+    const parts = token.split('.');
+    if (parts.length !== 3) return false;
+
+    const [headerPart, payloadPart, signaturePart] = parts;
+    if (!headerPart || !payloadPart || !signaturePart) return false;
+
+    let header: unknown;
+
+    try {
+        header = JSON.parse(Buffer.from(headerPart, 'base64url').toString('utf8'));
+    } catch {
+        return false;
+    }
+
+    if (typeof header !== 'object' || header === null) return false;
+
+    const candidate = header as Record<string, unknown>;
+
+    return (
+        candidate.alg === 'EdDSA' &&
+        typeof candidate.kid === 'string' &&
+        candidate.kid.startsWith(`${signerDid}#`)
+    );
+};
+
+export const createShareContentClient = (config: ShareContentClientConfig): ShareContentClient => {
+    const readBoundedBody = async (
+        response: Response,
+        maxBytes: number
+    ): Promise<{ ok: true; text: string } | { ok: false; error: ShareContentClientErrorCode }> => {
+        const body = response.body;
+
+        if (!body || typeof body.getReader !== 'function') {
+            try {
+                const text = await response.text();
+                if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+                    return { ok: false, error: 'RESPONSE_TOO_LARGE' };
+                }
+
+                return { ok: true, text };
+            } catch {
+                return { ok: false, error: 'NETWORK_ERROR' };
+            }
+        }
+
+        const reader = body.getReader();
+        const chunks: Uint8Array[] = [];
+        let total = 0;
+
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (!value) continue;
+
+                total += value.byteLength;
+
+                if (total > maxBytes) {
+                    await reader.cancel().catch(() => undefined);
+
+                    return { ok: false, error: 'RESPONSE_TOO_LARGE' };
+                }
+
+                chunks.push(value);
+            }
+        } catch {
+            return { ok: false, error: 'NETWORK_ERROR' };
+        }
+
+        return {
+            ok: true,
+            text: Buffer.concat(chunks.map(chunk => Buffer.from(chunk))).toString('utf8'),
+        };
+    };
+
+    const attemptOnce = async <T>(
+        op: ShareContentOperation,
+        bodyText: string,
+        requestHash: string,
+        expectedTuple: ShareContentTuple,
+        parseValue: (value: unknown) => T | null,
+        selectTuple: (value: T) => ShareContentTuple
+    ): Promise<ShareContentClientResult<T>> => {
+        const nowSeconds = Math.floor(config.now() / 1000);
+        const claims: ShareContentAuthorizationClaims = {
+            iss: config.signerDid,
+            aud: config.audience,
+            purpose: SHARE_CONTENT_AUTH_PURPOSE,
+            namespace: expectedTuple.namespace,
+            op,
+            shareId: expectedTuple.shareId,
+            contentVersion: expectedTuple.contentVersion,
+            ownerProfileId: expectedTuple.ownerProfileId,
+            objectId: expectedTuple.objectId,
+            operationId: expectedTuple.operationId,
+            requestHash,
+            iat: nowSeconds,
+            exp: nowSeconds + MAX_SHARE_CONTENT_TOKEN_TTL_SECONDS,
+            jti: generateJti(),
+        };
+
+        let token: string;
+
+        try {
+            token = await config.signer(claims);
+        } catch {
+            return { ok: false, error: 'SIGNING_FAILED' };
+        }
+
+        if (!validateSignedTokenHeader(token, config.signerDid)) {
+            return { ok: false, error: 'SIGNING_FAILED' };
+        }
+
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.requestTimeoutMs);
+
+        try {
+            let response: Response;
+
+            try {
+                response = await config.fetchImpl(buildUrl(config, op), {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${token}`,
+                        'content-type': 'application/json',
+                        accept: 'application/json',
+                        'cache-control': 'no-store',
+                    },
+                    body: bodyText,
+                    redirect: 'manual',
+                    signal: controller.signal,
+                });
+            } catch {
+                return {
+                    ok: false,
+                    error: controller.signal.aborted ? 'TIMEOUT' : 'NETWORK_ERROR',
+                };
+            }
+
+            if (response.status >= 300 && response.status < 400) {
+                return { ok: false, error: 'REDIRECT_REJECTED' };
+            }
+
+            if (response.status !== 200) {
+                // Drain a bounded amount so the socket can be reused; the body is
+                // discarded and never surfaces in the returned error.
+                await readBoundedBody(response, config.maxResponseBytes).catch(() => undefined);
+
+                return { ok: false, error: mapStatusToError(response.status) };
+            }
+
+            const read = await readBoundedBody(response, config.maxResponseBytes);
+
+            if (!read.ok) {
+                if (read.error === 'NETWORK_ERROR' && controller.signal.aborted) {
+                    return { ok: false, error: 'TIMEOUT' };
+                }
+
+                return { ok: false, error: read.error };
+            }
+
+            let parsed: unknown;
+
+            try {
+                parsed = JSON.parse(read.text);
+            } catch {
+                return { ok: false, error: 'MALFORMED_RESPONSE' };
+            }
+
+            const envelope = parseShareContentResponseEnvelope(parsed);
+
+            if (!envelope || !envelope.ok) return { ok: false, error: 'MALFORMED_RESPONSE' };
+
+            const value = parseValue(envelope.value);
+
+            if (!value) return { ok: false, error: 'MALFORMED_RESPONSE' };
+
+            if (!responseTupleMatches(selectTuple(value), expectedTuple)) {
+                return { ok: false, error: 'RESPONSE_TUPLE_MISMATCH' };
+            }
+
+            return { ok: true, value };
+        } finally {
+            clearTimeout(timer);
+        }
+    };
+
+    const perform = async <T>(
+        op: ShareContentOperation,
+        body: Record<string, unknown>,
+        expectedTuple: ShareContentTuple,
+        parseValue: (value: unknown) => T | null,
+        selectTuple: (value: T) => ShareContentTuple
+    ): Promise<ShareContentClientResult<T>> => {
+        if (!config.enabled) return { ok: false, error: 'DISABLED' };
+        if (!isValidTuple(expectedTuple)) return { ok: false, error: 'INVALID_INPUT' };
+
+        let bodyText: string;
+
+        try {
+            bodyText = JSON.stringify(body);
+        } catch {
+            return { ok: false, error: 'INVALID_INPUT' };
+        }
+
+        if (typeof bodyText !== 'string') return { ok: false, error: 'INVALID_INPUT' };
+        if (Buffer.byteLength(bodyText, 'utf8') > config.maxRequestBytes) {
+            return { ok: false, error: 'PAYLOAD_TOO_LARGE' };
+        }
+
+        let requestHash: string;
+
+        try {
+            requestHash = computeShareContentRequestBodyHash(body, {
+                maxBytes: config.maxRequestBytes,
+            });
+        } catch {
+            return { ok: false, error: 'INVALID_INPUT' };
+        }
+
+        let lastError: ShareContentClientErrorCode = 'NETWORK_ERROR';
+
+        for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
+            const result = await attemptOnce(
+                op,
+                bodyText,
+                requestHash,
+                expectedTuple,
+                parseValue,
+                selectTuple
+            );
+
+            if (result.ok) return result;
+
+            lastError = result.error;
+
+            if (!isTransientShareContentError(result.error) || attempt === config.maxAttempts) {
+                return result;
+            }
+
+            const backoff = Math.min(
+                config.retryBackoffMs * 2 ** (attempt - 1),
+                MAX_SHARE_CONTENT_RETRY_BACKOFF_MS
+            );
+
+            if (backoff > 0) await config.sleep(backoff);
+        }
+
+        return { ok: false, error: lastError };
+    };
+
+    return {
+        config,
+        put: async (request: ShareContentPutRequest) => {
+            if (!isValidEnvelope(request.envelope)) return { ok: false, error: 'INVALID_INPUT' };
+
+            return perform(
+                'put',
+                buildRequestBody(request),
+                request,
+                parseShareContentPutValue,
+                value => value.record
+            );
+        },
+        get: async (request: ShareContentTuple) =>
+            perform(
+                'get',
+                buildRequestBody(request),
+                request,
+                parseShareContentContentProjection,
+                value => value
+            ),
+        stat: async (request: ShareContentTuple) =>
+            perform(
+                'stat',
+                buildRequestBody(request),
+                request,
+                parseShareContentStatValue,
+                value => value
+            ),
+        delete: async (request: ShareContentTuple) =>
+            perform(
+                'delete',
+                buildRequestBody(request),
+                request,
+                parseShareContentDeleteValue,
+                value => value
+            ),
+        readRecovery: async (request: ShareContentTuple) =>
+            perform(
+                'readRecovery',
+                buildRequestBody(request),
+                request,
+                parseShareContentRecoveryProjection,
+                value => value
+            ),
+    };
+};
+
+export type { ShareContentClient, ShareContentClientConfig };
+export type {
+    ShareContentContentProjection,
+    ShareContentDeleteValue,
+    ShareContentPutValue,
+    ShareContentRecoveryProjection,
+    ShareContentStatValue,
+};

package/src/helpers/share-content-client/config.ts

@@ -0,0 +1,189 @@
+import {
+    DEFAULT_MAX_SHARE_CONTENT_REQUEST_BYTES,
+    DEFAULT_MAX_SHARE_CONTENT_RESPONSE_BYTES,
+    DEFAULT_SHARE_CONTENT_MAX_ATTEMPTS,
+    DEFAULT_SHARE_CONTENT_REQUEST_TIMEOUT_MS,
+    DEFAULT_SHARE_CONTENT_RETRY_BACKOFF_MS,
+    MAX_SHARE_CONTENT_RETRY_BACKOFF_MS,
+    ShareContentClientConfigurationError,
+    type ShareContentClientConfig,
+    type ShareContentTokenSigner,
+} from './types';
+
+/**
+ * Explicit, fail-closed client configuration. Nothing here reads environment
+ * variables or secrets: the wiring batch constructs it deliberately.
+ *
+ * A missing/invalid origin, namespace, audience, signer DID or signer function
+ * collapses to the disabled configuration, so a partially configured deployment
+ * never performs a signed request. There is deliberately no offline or unsigned
+ * bypass.
+ */
+
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+const disabledSigner: ShareContentTokenSigner = async () => {
+    throw new ShareContentClientConfigurationError('share-content client is disabled');
+};
+
+export const DISABLED_SHARE_CONTENT_CLIENT_CONFIG: ShareContentClientConfig = Object.freeze({
+    enabled: false,
+    origin: '',
+    namespace: '',
+    audience: '',
+    signerDid: '',
+    allowInsecureLoopback: false,
+    signer: disabledSigner,
+    requestTimeoutMs: DEFAULT_SHARE_CONTENT_REQUEST_TIMEOUT_MS,
+    maxAttempts: 1,
+    retryBackoffMs: 0,
+    maxRequestBytes: DEFAULT_MAX_SHARE_CONTENT_REQUEST_BYTES,
+    maxResponseBytes: DEFAULT_MAX_SHARE_CONTENT_RESPONSE_BYTES,
+    now: () => Date.now(),
+    sleep: (ms: number) => new Promise(resolve => setTimeout(resolve, ms)),
+    fetchImpl: ((...args: Parameters<typeof fetch>) => fetch(...args)) as typeof fetch,
+}) as ShareContentClientConfig;
+
+const isOpaqueIdentifier = (value: unknown, maxLength = 128): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= maxLength &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+const isBoundedInteger = (value: unknown, minimum: number, maximum: number): value is number =>
+    typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value >= minimum &&
+    value <= maximum;
+
+/**
+ * Validate a configured origin. Only an `https:` origin is trusted; a loopback
+ * `http:` origin is accepted only when `allowInsecureLoopback` is explicitly set
+ * for local tests/development, and the cryptographic auth path is unchanged.
+ */
+export const validateShareContentOrigin = (
+    origin: unknown,
+    allowInsecureLoopback: boolean
+): { ok: true; origin: string } | { ok: false; reason: string } => {
+    if (typeof origin !== 'string' || origin.trim().length === 0) {
+        return { ok: false, reason: 'origin must be a non-empty string' };
+    }
+
+    let url: URL;
+
+    try {
+        url = new URL(origin);
+    } catch {
+        return { ok: false, reason: 'origin must be a valid absolute URL' };
+    }
+
+    if (url.username || url.password) {
+        return { ok: false, reason: 'origin must not contain userinfo' };
+    }
+    if (url.search || url.hash) {
+        return { ok: false, reason: 'origin must not contain a query or fragment' };
+    }
+    if (url.pathname !== '/' && url.pathname !== '') {
+        return { ok: false, reason: 'origin must not contain a path' };
+    }
+
+    if (url.protocol === 'https:') {
+        return { ok: true, origin: `${url.protocol}//${url.host}` };
+    }
+
+    if (url.protocol === 'http:') {
+        if (!allowInsecureLoopback) {
+            return { ok: false, reason: 'insecure http origin requires allowInsecureLoopback' };
+        }
+        if (!LOOPBACK_HOSTS.has(url.hostname)) {
+            return { ok: false, reason: 'insecure http origin must be loopback' };
+        }
+
+        return { ok: true, origin: `${url.protocol}//${url.host}` };
+    }
+
+    return { ok: false, reason: 'origin must use https (or loopback http for local tests)' };
+};
+
+/** Build a validated, frozen client configuration, or the disabled config. */
+export const resolveShareContentClientConfig = (raw: unknown): ShareContentClientConfig => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+    }
+
+    const source = raw as Record<string, unknown>;
+
+    if (source.enabled !== true) return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+
+    const allowInsecureLoopback = source.allowInsecureLoopback === true;
+    const originResult = validateShareContentOrigin(source.origin, allowInsecureLoopback);
+
+    if (!originResult.ok) return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+
+    if (!isOpaqueIdentifier(source.namespace)) return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+    if (typeof source.audience !== 'string' || source.audience.trim().length === 0) {
+        return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+    }
+    if (typeof source.signerDid !== 'string' || !source.signerDid.startsWith('did:')) {
+        return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+    }
+    if (typeof source.signer !== 'function') return DISABLED_SHARE_CONTENT_CLIENT_CONFIG;
+
+    const signer = source.signer as ShareContentTokenSigner;
+    const requestTimeoutMs = isBoundedInteger(source.requestTimeoutMs, 1, 120_000)
+        ? source.requestTimeoutMs
+        : DEFAULT_SHARE_CONTENT_REQUEST_TIMEOUT_MS;
+    const maxAttempts = isBoundedInteger(source.maxAttempts, 1, 10)
+        ? source.maxAttempts
+        : DEFAULT_SHARE_CONTENT_MAX_ATTEMPTS;
+    const retryBackoffMs = isBoundedInteger(
+        source.retryBackoffMs,
+        0,
+        MAX_SHARE_CONTENT_RETRY_BACKOFF_MS
+    )
+        ? source.retryBackoffMs
+        : DEFAULT_SHARE_CONTENT_RETRY_BACKOFF_MS;
+    const maxRequestBytes = isBoundedInteger(
+        source.maxRequestBytes,
+        1024,
+        DEFAULT_MAX_SHARE_CONTENT_REQUEST_BYTES
+    )
+        ? source.maxRequestBytes
+        : DEFAULT_MAX_SHARE_CONTENT_REQUEST_BYTES;
+    const maxResponseBytes = isBoundedInteger(
+        source.maxResponseBytes,
+        1024,
+        DEFAULT_MAX_SHARE_CONTENT_RESPONSE_BYTES
+    )
+        ? source.maxResponseBytes
+        : DEFAULT_MAX_SHARE_CONTENT_RESPONSE_BYTES;
+
+    const now = typeof source.now === 'function' ? (source.now as () => number) : () => Date.now();
+    const sleep =
+        typeof source.sleep === 'function'
+            ? (source.sleep as (ms: number) => Promise<void>)
+            : (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+    const fetchImpl =
+        typeof source.fetchImpl === 'function'
+            ? (source.fetchImpl as typeof fetch)
+            : (((...args: Parameters<typeof fetch>) => fetch(...args)) as typeof fetch);
+
+    return Object.freeze({
+        enabled: true,
+        origin: originResult.origin,
+        namespace: source.namespace,
+        audience: source.audience,
+        signerDid: source.signerDid,
+        allowInsecureLoopback,
+        signer,
+        requestTimeoutMs,
+        maxAttempts,
+        retryBackoffMs,
+        maxRequestBytes,
+        maxResponseBytes,
+        now,
+        sleep,
+        fetchImpl,
+    }) as ShareContentClientConfig;
+};

package/src/helpers/share-content-client/index.ts

@@ -0,0 +1,27 @@
+export * from './types';
+export {
+    canonicalizeShareContentRequestBody,
+    computeShareContentRequestBodyHash,
+    isSha256Hex,
+    ShareContentCanonicalizationError,
+} from './canonical';
+export {
+    DISABLED_SHARE_CONTENT_CLIENT_CONFIG,
+    resolveShareContentClientConfig,
+    validateShareContentOrigin,
+} from './config';
+export { createShareContentClient } from './client';
+export {
+    parseShareContentActiveSummary,
+    parseShareContentContentProjection,
+    parseShareContentDeleteValue,
+    parseShareContentPutValue,
+    parseShareContentRecoveryProjection,
+    parseShareContentResponseEnvelope,
+    parseShareContentStatValue,
+    parseShareContentTombstoneSummary,
+} from './responses';
+
+// The runtime did:web signing adapter deliberately lives outside this barrel:
+// import `@helpers/share-content-client/adapters` from the wiring layer so unit
+// tests of the transport never load the LearnCard/environment graph.