@learncard/network-brain-service 3.18.0 → 3.19.1

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-coordinator/budget-helpers.ts

@@ -0,0 +1,53 @@
+import type { MaintenanceBudget } from './types';
+
+/**
+ * True only for the maintenance budget that opted into whole-unit admission.
+ * Legacy/direct callers that pass a bare budget keep the reviewed `exhausted`
+ * gate and are never subjected to the extra mid-unit rechecks.
+ */
+export const budgetHasUnitReserve = (budget: MaintenanceBudget | undefined): boolean =>
+    budget !== undefined && typeof budget.reserveMs === 'function';
+
+/**
+ * Cooperative budget helpers shared by the recovery and cleanup runners.
+ *
+ * `budgetAllows` is deliberately conservative only when the caller opted into the
+ * maintenance reserve (`reserveMs`). Direct/legacy callers that pass a bare budget
+ * keep the reviewed `exhausted()` behaviour, so this cannot silently disable a
+ * one-shot runner that predates the maintenance scheduler.
+ */
+export const budgetAllows = (budget: MaintenanceBudget | undefined, costMs: number): boolean => {
+    if (!budget) return true;
+
+    if (typeof budget.reserveMs !== 'function' || !Number.isFinite(costMs)) {
+        return !budget.exhausted();
+    }
+
+    const remaining = budget.remainingMs();
+    if (!Number.isFinite(remaining)) return false;
+
+    return remaining - budget.reserveMs() >= Math.max(0, costMs);
+};
+
+/**
+ * Bound a per-call managed-transaction timeout by the time actually left before
+ * the pass reserve. The result is always >= 1 so an explicit maintenance
+ * transaction still has a positive server-side bound; it can never extend the
+ * configured timeout.
+ */
+export const boundTransactionTimeout = (
+    configuredTimeoutMs: number | undefined,
+    budget: MaintenanceBudget | undefined
+): number | undefined => {
+    if (configuredTimeoutMs === undefined) return undefined;
+    if (!budget) return configuredTimeoutMs;
+
+    const remaining = budget.remainingMs();
+    if (!Number.isFinite(remaining)) return configuredTimeoutMs;
+
+    const reserved = typeof budget.reserveMs === 'function' ? budget.reserveMs() : 0;
+    const available = remaining - reserved;
+    if (!Number.isFinite(available)) return configuredTimeoutMs;
+
+    return Math.max(1, Math.trunc(Math.min(configuredTimeoutMs, available)));
+};