@learncard/network-brain-service 3.19.0 → 4.0.0

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

@@ -0,0 +1,273 @@
+import type {
+    ShareContentActiveSummary,
+    ShareContentContentProjection,
+    ShareContentDeleteValue,
+    ShareContentEnvelope,
+    ShareContentOwnerRecovery,
+    ShareContentPutValue,
+    ShareContentRecoveryProjection,
+    ShareContentStatValue,
+    ShareContentTombstoneSummary,
+} from './types';
+
+/**
+ * Narrow local validators for the LearnCloud JSON response envelope. They are
+ * intentionally hand-written (rather than reusing a shared schema) so the
+ * transport contract is pinned here: every accepted field is checked, unknown
+ * fields are rejected, and no opaque payload is ever coerced or rewritten.
+ *
+ * Dates arrive as ISO-8601 strings because the C2 repository's `Date` values are
+ * JSON-serialized by the route.
+ */
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+const isNonEmptyString = (value: unknown): value is string =>
+    typeof value === 'string' && value.length > 0;
+
+const isSafeIntegerAtLeast = (value: unknown, minimum: number): value is number =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+
+const isSha256Hex = (value: unknown): value is string =>
+    typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+
+const hasExactKeys = (value: Record<string, unknown>, keys: readonly string[]): boolean => {
+    const actual = Object.keys(value);
+
+    return actual.length === keys.length && actual.every(key => keys.includes(key));
+};
+
+const parseEnvelope = (value: unknown): ShareContentEnvelope | null => {
+    if (!isPlainObject(value) || !hasExactKeys(value, ['v', 'alg', 'iv', 'ct'])) return null;
+    if (value.v !== 1 || value.alg !== 'A256GCM') return null;
+    if (!isNonEmptyString(value.iv) || !isNonEmptyString(value.ct)) return null;
+
+    return { v: 1, alg: 'A256GCM', iv: value.iv, ct: value.ct };
+};
+
+const parseOwnerRecovery = (value: unknown): ShareContentOwnerRecovery | null =>
+    isPlainObject(value) ? { ...value } : null;
+
+const parseTupleFields = (
+    value: Record<string, unknown>
+): {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+} | null => {
+    if (!isNonEmptyString(value.namespace)) return null;
+    if (!isNonEmptyString(value.ownerProfileId)) return null;
+    if (!isNonEmptyString(value.shareId)) return null;
+    if (!isSafeIntegerAtLeast(value.contentVersion, 1)) return null;
+    if (!isNonEmptyString(value.objectId)) return null;
+    if (!isNonEmptyString(value.operationId)) return null;
+
+    return {
+        namespace: value.namespace,
+        ownerProfileId: value.ownerProfileId,
+        shareId: value.shareId,
+        contentVersion: value.contentVersion,
+        objectId: value.objectId,
+        operationId: value.operationId,
+    };
+};
+
+const parseActiveSummary = (value: unknown): ShareContentActiveSummary | null => {
+    if (!isPlainObject(value) || value.kind !== 'active') return null;
+    if (
+        !hasExactKeys(value, [
+            'kind',
+            'namespace',
+            'ownerProfileId',
+            'shareId',
+            'contentVersion',
+            'objectId',
+            'operationId',
+            'contentHash',
+            'payloadHash',
+            'ciphertextBytes',
+            'recoveryBytes',
+            'createdAt',
+        ])
+    )
+        return null;
+
+    const tuple = parseTupleFields(value);
+
+    if (!tuple) return null;
+    if (!isSha256Hex(value.contentHash) || !isSha256Hex(value.payloadHash)) return null;
+    if (!isSafeIntegerAtLeast(value.ciphertextBytes, 0)) return null;
+    if (!isSafeIntegerAtLeast(value.recoveryBytes, 0)) return null;
+    if (!isNonEmptyString(value.createdAt)) return null;
+
+    return {
+        kind: 'active',
+        ...tuple,
+        contentHash: value.contentHash,
+        payloadHash: value.payloadHash,
+        ciphertextBytes: value.ciphertextBytes,
+        recoveryBytes: value.recoveryBytes,
+        createdAt: value.createdAt,
+    };
+};
+
+const parseTombstoneSummary = (value: unknown): ShareContentTombstoneSummary | null => {
+    if (!isPlainObject(value) || value.kind !== 'tombstone') return null;
+
+    const allowed = [
+        'kind',
+        'namespace',
+        'ownerProfileId',
+        'shareId',
+        'contentVersion',
+        'objectId',
+        'operationId',
+        'contentHash',
+        'deletedAt',
+    ];
+
+    if (Object.keys(value).some(key => !allowed.includes(key))) return null;
+
+    const tuple = parseTupleFields(value);
+
+    if (!tuple) return null;
+    if (value.contentHash !== undefined && !isSha256Hex(value.contentHash)) return null;
+    if (!isNonEmptyString(value.deletedAt)) return null;
+
+    return {
+        kind: 'tombstone',
+        ...tuple,
+        ...(value.contentHash !== undefined ? { contentHash: value.contentHash } : {}),
+        deletedAt: value.deletedAt,
+    };
+};
+
+export const parseShareContentActiveSummary = parseActiveSummary;
+export const parseShareContentTombstoneSummary = parseTombstoneSummary;
+
+export const parseShareContentStatValue = (value: unknown): ShareContentStatValue | null =>
+    parseActiveSummary(value) ?? parseTombstoneSummary(value);
+
+export const parseShareContentDeleteValue = (value: unknown): ShareContentDeleteValue | null =>
+    parseTombstoneSummary(value);
+
+export const parseShareContentPutValue = (value: unknown): ShareContentPutValue | null => {
+    if (!isPlainObject(value) || !hasExactKeys(value, ['status', 'record'])) return null;
+    if (value.status !== 'created' && value.status !== 'idempotent') return null;
+
+    const record = parseActiveSummary(value.record);
+
+    if (!record) return null;
+
+    return { status: value.status, record };
+};
+
+export const parseShareContentContentProjection = (
+    value: unknown
+): ShareContentContentProjection | null => {
+    if (!isPlainObject(value) || value.kind !== 'active') return null;
+    if (
+        !hasExactKeys(value, [
+            'kind',
+            'namespace',
+            'ownerProfileId',
+            'shareId',
+            'contentVersion',
+            'objectId',
+            'operationId',
+            'contentHash',
+            'payloadHash',
+            'envelope',
+            'ciphertextBytes',
+            'createdAt',
+        ])
+    )
+        return null;
+
+    const tuple = parseTupleFields(value);
+    const envelope = parseEnvelope(value.envelope);
+
+    if (!tuple || !envelope) return null;
+    if (!isSha256Hex(value.contentHash) || !isSha256Hex(value.payloadHash)) return null;
+    if (!isSafeIntegerAtLeast(value.ciphertextBytes, 0)) return null;
+    if (!isNonEmptyString(value.createdAt)) return null;
+
+    return {
+        kind: 'active',
+        ...tuple,
+        contentHash: value.contentHash,
+        payloadHash: value.payloadHash,
+        envelope,
+        ciphertextBytes: value.ciphertextBytes,
+        createdAt: value.createdAt,
+    };
+};
+
+export const parseShareContentRecoveryProjection = (
+    value: unknown
+): ShareContentRecoveryProjection | null => {
+    if (!isPlainObject(value) || value.kind !== 'active') return null;
+    if (
+        !hasExactKeys(value, [
+            'kind',
+            'namespace',
+            'ownerProfileId',
+            'shareId',
+            'contentVersion',
+            'objectId',
+            'operationId',
+            'contentHash',
+            'payloadHash',
+            'ownerEncryptedRecovery',
+            'recoveryBytes',
+            'createdAt',
+        ])
+    )
+        return null;
+
+    const tuple = parseTupleFields(value);
+    const recovery = parseOwnerRecovery(value.ownerEncryptedRecovery);
+
+    if (!tuple || !recovery) return null;
+    if (!isSha256Hex(value.contentHash) || !isSha256Hex(value.payloadHash)) return null;
+    if (!isSafeIntegerAtLeast(value.recoveryBytes, 0)) return null;
+    if (!isNonEmptyString(value.createdAt)) return null;
+
+    return {
+        kind: 'active',
+        ...tuple,
+        contentHash: value.contentHash,
+        payloadHash: value.payloadHash,
+        ownerEncryptedRecovery: recovery,
+        recoveryBytes: value.recoveryBytes,
+        createdAt: value.createdAt,
+    };
+};
+
+/** Parse the fixed `{ok:true,value}` / `{ok:false,error}` JSON envelope. */
+export const parseShareContentResponseEnvelope = (
+    parsed: unknown
+): { ok: true; value: unknown } | { ok: false; error: string } | null => {
+    if (!isPlainObject(parsed)) return null;
+
+    if (parsed.ok === true) {
+        if (!('value' in parsed)) return null;
+
+        return { ok: true, value: parsed.value };
+    }
+
+    if (parsed.ok === false) {
+        if (typeof parsed.error !== 'string' || parsed.error.length === 0) return null;
+
+        return { ok: false, error: parsed.error };
+    }
+
+    return null;
+};

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

@@ -0,0 +1,253 @@
+/**
+ * LC-2187 Brain → LearnCloud share-content HTTP client types.
+ *
+ * This module defines the *transport* grammar for the fixed server-to-server
+ * contract. It is deliberately local to brain-service: production must never
+ * import LearnCloud runtime code, so the few shared literals (the six-field
+ * tuple, the operation names, the request-hash canon) are restated here and
+ * pinned by cross-implementation contract tests.
+ *
+ * The client never persists or logs the ciphertext, the owner recovery JWE, the
+ * signed token or the claims. Every value that crosses this boundary is either a
+ * non-secret binding or an already-encrypted opaque payload.
+ */
+
+/**
+ * The exact operation allowlist. The operation is carried by the route, not the
+ * request body, so it is a client-side parameter, never a body field.
+ */
+export const SHARE_CONTENT_OPERATIONS = ['put', 'get', 'stat', 'delete', 'readRecovery'] as const;
+
+export type ShareContentOperation = (typeof SHARE_CONTENT_OPERATIONS)[number];
+
+/** Signed purpose claim accepted by the C1 verifier. */
+export const SHARE_CONTENT_AUTH_PURPOSE = 'lc-share-content/v1' as const;
+
+/** Bound on the complete JSON request body. */
+export const DEFAULT_MAX_SHARE_CONTENT_REQUEST_BYTES = 1024 * 1024;
+/** Bound on the complete JSON response body. */
+export const DEFAULT_MAX_SHARE_CONTENT_RESPONSE_BYTES = 2 * 1024 * 1024;
+/** Maximum signed token lifetime in seconds; the contract caps this at 60. */
+export const MAX_SHARE_CONTENT_TOKEN_TTL_SECONDS = 60;
+export const DEFAULT_SHARE_CONTENT_REQUEST_TIMEOUT_MS = 10_000;
+export const DEFAULT_SHARE_CONTENT_MAX_ATTEMPTS = 3;
+export const DEFAULT_SHARE_CONTENT_RETRY_BACKOFF_MS = 200;
+export const MAX_SHARE_CONTENT_RETRY_BACKOFF_MS = 5_000;
+
+/** A256GCM envelope exactly as stored by LearnCloud. */
+export type ShareContentEnvelope = {
+    v: 1;
+    alg: 'A256GCM';
+    iv: string;
+    ct: string;
+};
+
+/** Opaque owner-encrypted recovery JWE. Never interpreted by this module. */
+export type ShareContentOwnerRecovery = Record<string, unknown>;
+
+/**
+ * The exact six-field immutable tuple. Every request — including `put` — carries
+ * these fields and the route supplies the operation.
+ */
+export type ShareContentTuple = {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+};
+
+export type ShareContentPutRequest = ShareContentTuple & {
+    envelope: ShareContentEnvelope;
+    ownerEncryptedRecovery: ShareContentOwnerRecovery;
+};
+
+/** Claims signed into the JWT-VP `nonce`; mirrors the reviewed C1 claim list. */
+export type ShareContentAuthorizationClaims = {
+    iss: string;
+    aud: string;
+    purpose: typeof SHARE_CONTENT_AUTH_PURPOSE;
+    namespace: string;
+    op: ShareContentOperation;
+    shareId: string;
+    contentVersion: number;
+    ownerProfileId: string;
+    objectId: string;
+    operationId: string;
+    requestHash: string;
+    iat: number;
+    exp: number;
+    jti: string;
+};
+
+/**
+ * Injected signing adapter. The runtime implementation wraps the existing
+ * did:web LearnCard primitives; tests inject a fake or a checked-in DIDKit
+ * fixture. `claims` already contains a fresh CSPRNG `jti` and bounded times.
+ */
+export type ShareContentTokenSigner = (claims: ShareContentAuthorizationClaims) => Promise<string>;
+
+/** Response value: active object summary (no ciphertext or recovery). */
+export type ShareContentActiveSummary = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: string;
+    payloadHash: string;
+    ciphertextBytes: number;
+    recoveryBytes: number;
+    createdAt: string;
+};
+
+/** Response value: permanent tombstone summary. */
+export type ShareContentTombstoneSummary = {
+    kind: 'tombstone';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash?: string;
+    deletedAt: string;
+};
+
+export type ShareContentStatValue = ShareContentActiveSummary | ShareContentTombstoneSummary;
+
+/** Response value for `put`. */
+export type ShareContentPutValue = {
+    status: 'created' | 'idempotent';
+    record: ShareContentActiveSummary;
+};
+
+/** Response value for `get`: content projection, never owner recovery. */
+export type ShareContentContentProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: string;
+    payloadHash: string;
+    envelope: ShareContentEnvelope;
+    ciphertextBytes: number;
+    createdAt: string;
+};
+
+/** Response value for `readRecovery`: owner-only projection, never ciphertext. */
+export type ShareContentRecoveryProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: string;
+    payloadHash: string;
+    ownerEncryptedRecovery: ShareContentOwnerRecovery;
+    recoveryBytes: number;
+    createdAt: string;
+};
+
+/** Response value for `delete`: the permanent tombstone. */
+export type ShareContentDeleteValue = ShareContentTombstoneSummary;
+
+/**
+ * Stable, non-secret transport/repository codes. Routes and callers must map
+ * every one to a generic external result; none of them carry token or body data.
+ */
+export type ShareContentClientErrorCode =
+    | 'DISABLED'
+    | 'INVALID_INPUT'
+    | 'UNAUTHORIZED'
+    | 'NOT_FOUND'
+    | 'CONFLICT'
+    | 'PAYLOAD_TOO_LARGE'
+    | 'UNAVAILABLE'
+    | 'UNEXPECTED_STATUS'
+    | 'MALFORMED_RESPONSE'
+    | 'RESPONSE_TOO_LARGE'
+    | 'RESPONSE_TUPLE_MISMATCH'
+    | 'REDIRECT_REJECTED'
+    | 'TIMEOUT'
+    | 'NETWORK_ERROR'
+    | 'SIGNING_FAILED';
+
+export type ShareContentClientResult<T> =
+    { ok: true; value: T } | { ok: false; error: ShareContentClientErrorCode };
+
+/** Transport errors that a bounded retry (with a fresh token/jti) may re-attempt. */
+export const TRANSIENT_SHARE_CONTENT_ERRORS: readonly ShareContentClientErrorCode[] = [
+    'UNAVAILABLE',
+    'TIMEOUT',
+    'NETWORK_ERROR',
+];
+
+export const isTransientShareContentError = (code: ShareContentClientErrorCode): boolean =>
+    TRANSIENT_SHARE_CONTENT_ERRORS.includes(code);
+
+/** Configuration/validation failure raised before any network I/O. */
+export class ShareContentClientConfigurationError extends Error {
+    readonly code = 'SHARE_CONTENT_CLIENT_CONFIGURATION_ERROR';
+
+    constructor(message: string) {
+        super(message);
+        this.name = 'ShareContentClientConfigurationError';
+    }
+}
+
+export type ShareContentClientConfig = {
+    /** Fail-closed switch. When false every operation returns `DISABLED`. */
+    enabled: boolean;
+    /** Trusted origin, e.g. `https://learncloud.example`. No path/query/userinfo. */
+    origin: string;
+    /** Explicit stable opaque namespace accepted by C1/C2 (no `%`/`:`). */
+    namespace: string;
+    /** LearnCloud service DID (the token audience). */
+    audience: string;
+    /** Brain service DID the signer is expected to sign as. */
+    signerDid: string;
+    /**
+     * When true, a loopback `http://localhost`/`127.0.0.1`/`[::1]` origin is
+     * accepted for local tests/development. The cryptographic auth path is
+     * identical; there is never an unsigned bypass.
+     */
+    allowInsecureLoopback: boolean;
+    signer: ShareContentTokenSigner;
+    requestTimeoutMs: number;
+    maxAttempts: number;
+    retryBackoffMs: number;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
+    /** Epoch-milliseconds clock, injectable for deterministic tests. */
+    now: () => number;
+    /** Bound sleep, injectable so retry tests do not wait. */
+    sleep: (ms: number) => Promise<void>;
+    /** Injectable fetch for tests; defaults to the global fetch. */
+    fetchImpl: typeof fetch;
+};
+
+export type ShareContentClient = {
+    readonly config: ShareContentClientConfig;
+    put: (
+        request: ShareContentPutRequest
+    ) => Promise<ShareContentClientResult<ShareContentPutValue>>;
+    get: (
+        request: ShareContentTuple
+    ) => Promise<ShareContentClientResult<ShareContentContentProjection>>;
+    stat: (request: ShareContentTuple) => Promise<ShareContentClientResult<ShareContentStatValue>>;
+    delete: (
+        request: ShareContentTuple
+    ) => Promise<ShareContentClientResult<ShareContentDeleteValue>>;
+    readRecovery: (
+        request: ShareContentTuple
+    ) => Promise<ShareContentClientResult<ShareContentRecoveryProjection>>;
+};

package/src/helpers/share-link-attachment-access.ts

@@ -0,0 +1,87 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { getShareLinkRequestHashSecret } from './share-link-lifecycle';
+import type { ShareLinkRecord } from '../models/ShareLink';
+
+const TTL_MS = 60 * 1000;
+const sign = (text: string): string =>
+    createHmac('sha256', getShareLinkRequestHashSecret()).update(text).digest('base64url');
+const binding = (record: ShareLinkRecord, namespace: string, sourceIp?: string): string =>
+    sign(
+        JSON.stringify([
+            'attachment-access-v1',
+            namespace,
+            record.ownerProfileId,
+            record.id,
+            record.contentVersion,
+            record.attachmentId,
+            record.attachmentChunkCount,
+            record.passcodeHash ?? null,
+            sourceIp ?? null,
+        ])
+    );
+
+/** Opaque keyed binding never exposes the password verifier or internal owner/namespace. */
+export const mintShareAttachmentAccessToken = (
+    record: ShareLinkRecord,
+    namespace: string,
+    sourceIp: string | undefined,
+    now: Date
+): string => {
+    const body = Buffer.from(
+        JSON.stringify({
+            v: 1,
+            expiresAt: now.getTime() + TTL_MS,
+            nonce: randomUUID(),
+            binding: binding(record, namespace, sourceIp),
+        })
+    ).toString('base64url');
+    return `${body}.${sign(`attachment-grant-v1:${body}`)}`;
+};
+
+/** A grant only amortizes a successful password check; active/current authorization remains mandatory. */
+export const verifyShareAttachmentAccessToken = (
+    token: string,
+    record: ShareLinkRecord,
+    namespace: string,
+    sourceIp: string | undefined,
+    now: Date
+): boolean => {
+    try {
+        const parts = token.split('.');
+        const bodyPart = parts[0];
+        const signature = parts[1];
+        if (
+            parts.length !== 2 ||
+            !bodyPart ||
+            !signature ||
+            signature.length !== 43 ||
+            token.length > 2048
+        )
+            return false;
+        const bytes = Buffer.from(bodyPart, 'base64url');
+        if (bytes.toString('base64url') !== bodyPart) return false;
+        const actual = Buffer.from(signature, 'base64url');
+        const expected = Buffer.from(sign(`attachment-grant-v1:${bodyPart}`), 'base64url');
+        if (
+            actual.length !== expected.length ||
+            actual.toString('base64url') !== signature ||
+            !timingSafeEqual(actual, expected)
+        )
+            return false;
+        const body: unknown = JSON.parse(bytes.toString('utf8'));
+        if (!body || typeof body !== 'object' || Array.isArray(body)) return false;
+        const value = body as Record<string, unknown>;
+        if (
+            value.v !== 1 ||
+            typeof value.expiresAt !== 'number' ||
+            !Number.isSafeInteger(value.expiresAt) ||
+            value.expiresAt <= now.getTime() ||
+            value.expiresAt > now.getTime() + TTL_MS ||
+            value.binding !== binding(record, namespace, sourceIp)
+        )
+            return false;
+        return true;
+    } catch {
+        return false;
+    }
+};