@learncard/network-brain-service 4.0.4 → 4.1.1

package/src/helpers/bedrock-embedding.helpers.ts

@@ -0,0 +1,243 @@
+import { BedrockRuntimeClient, InvokeModelCommand } from '@aws-sdk/client-bedrock-runtime';
+
+import { NOVA2_MAX_TEXT_CHARS } from '../config/skillEmbedding';
+
+/**
+ * LC-2206 Bedrock adapter for Amazon Nova 2 Multimodal Embeddings.
+ *
+ * Style follows lca-api's Bedrock image adapter (LC-2205): one InvokeModel per request,
+ * SigV4 with the execution role's rotating credentials (never a long-term
+ * AWS_BEARER_TOKEN_BEDROCK key), no SDK retries, a hard timeout, and sanitised errors that
+ * never carry provider bodies, input text, credentials or vectors.
+ */
+
+/** `index` embeds stored skills (GENERIC_INDEX); `query` embeds search text (TEXT_RETRIEVAL). */
+export type EmbeddingPurpose = 'index' | 'query';
+
+export type BedrockEmbeddingConfig = {
+    modelId: string;
+    region: string;
+    dimension: number;
+    timeoutMs: number;
+};
+
+export type SkillEmbeddingErrorCode =
+    | 'disabled'
+    | 'invalid_input'
+    | 'throttled'
+    | 'unavailable'
+    | 'access_denied'
+    | 'timeout'
+    | 'invalid_response'
+    | 'failed';
+
+export class SkillEmbeddingError extends Error {
+    readonly code: SkillEmbeddingErrorCode;
+
+    readonly retryable: boolean;
+
+    readonly httpStatus?: number;
+
+    constructor(code: SkillEmbeddingErrorCode, httpStatus?: number) {
+        super(`Skill embedding failed (${code})`);
+        this.name = 'SkillEmbeddingError';
+        this.code = code;
+        this.retryable = code === 'throttled' || code === 'unavailable' || code === 'timeout';
+        this.httpStatus = httpStatus;
+    }
+}
+
+export const isSkillEmbeddingError = (error: unknown): error is SkillEmbeddingError =>
+    error instanceof SkillEmbeddingError;
+
+/** Raw InvokeModel transport; injectable so unit tests never reach AWS. */
+export type BedrockInvoke = (
+    request: { modelId: string; body: string },
+    options: { abortSignal: AbortSignal }
+) => Promise<Uint8Array>;
+
+export const buildNovaEmbeddingRequest = (
+    text: string,
+    purpose: EmbeddingPurpose,
+    dimension: number
+) => ({
+    schemaVersion: 'nova-multimodal-embed-v1',
+    taskType: 'SINGLE_EMBEDDING',
+    singleEmbeddingParams: {
+        embeddingPurpose: purpose === 'index' ? 'GENERIC_INDEX' : 'TEXT_RETRIEVAL',
+        embeddingDimension: dimension,
+        // Fail instead of silently embedding a truncated text; callers bound input length.
+        text: { truncationMode: 'NONE', value: text },
+    },
+});
+
+/** L2-normalise so cosine and dot-product scores agree (AI Passport does the same). */
+export const normalizeEmbedding = (vector: number[]): number[] => {
+    const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+    if (!Number.isFinite(norm) || norm === 0) throw new SkillEmbeddingError('invalid_response');
+    return vector.map(value => value / norm);
+};
+
+/** Validate the documented Nova InvokeModel envelope: exactly one finite TEXT vector. */
+export const parseNovaEmbeddingResponse = (body: Uint8Array, dimension: number): number[] => {
+    let parsed: unknown;
+
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(body));
+    } catch {
+        throw new SkillEmbeddingError('invalid_response');
+    }
+
+    const rows = (parsed as { embeddings?: unknown } | null)?.embeddings;
+    if (!Array.isArray(rows) || rows.length !== 1)
+        throw new SkillEmbeddingError('invalid_response');
+
+    const row = rows[0] as {
+        embeddingType?: unknown;
+        embedding?: unknown;
+        truncatedCharLength?: unknown;
+    } | null;
+
+    if (
+        !row ||
+        row.embeddingType !== 'TEXT' ||
+        row.truncatedCharLength !== undefined ||
+        !Array.isArray(row.embedding) ||
+        row.embedding.length !== dimension ||
+        !row.embedding.every(value => typeof value === 'number' && Number.isFinite(value))
+    ) {
+        throw new SkillEmbeddingError('invalid_response');
+    }
+
+    return normalizeEmbedding(row.embedding as number[]);
+};
+
+const providerStatus = (error: unknown): number | undefined => {
+    if (!error || typeof error !== 'object') return undefined;
+    const { $metadata: metadata } = error as { $metadata?: { httpStatusCode?: unknown } };
+    return typeof metadata?.httpStatusCode === 'number' ? metadata.httpStatusCode : undefined;
+};
+
+const providerName = (error: unknown): string | undefined => {
+    if (!error || typeof error !== 'object') return undefined;
+    const { name } = error as { name?: unknown };
+    return typeof name === 'string' ? name : undefined;
+};
+
+/** Map an SDK failure to a code. The provider message and body are deliberately dropped. */
+export const sanitizeBedrockError = (error: unknown): SkillEmbeddingError => {
+    if (error instanceof SkillEmbeddingError) return error;
+
+    const status = providerStatus(error);
+    const name = providerName(error);
+
+    if (name === 'AbortError' || name === 'TimeoutError') return new SkillEmbeddingError('timeout');
+    if (
+        status === 429 ||
+        name === 'ThrottlingException' ||
+        name === 'ServiceQuotaExceededException'
+    ) {
+        return new SkillEmbeddingError('throttled', 429);
+    }
+    if (status === 403 || name === 'AccessDeniedException') {
+        return new SkillEmbeddingError('access_denied', 403);
+    }
+    if (
+        status === 503 ||
+        status === 504 ||
+        name === 'ServiceUnavailableException' ||
+        name === 'ModelNotReadyException' ||
+        name === 'ModelTimeoutException'
+    ) {
+        return new SkillEmbeddingError('unavailable', status);
+    }
+    if (status === 400 || name === 'ValidationException') {
+        return new SkillEmbeddingError('invalid_input', 400);
+    }
+
+    return new SkillEmbeddingError('failed', status);
+};
+
+const clients = new Map<string, BedrockRuntimeClient>();
+
+const getClient = (config: BedrockEmbeddingConfig): BedrockRuntimeClient => {
+    const key = `${config.region}:${config.timeoutMs}`;
+    let client = clients.get(key);
+
+    if (!client) {
+        client = new BedrockRuntimeClient({
+            region: config.region,
+            // One paid attempt per call; the backfill decides whether to retry later.
+            maxAttempts: 1,
+            // Execution-role SigV4 only, matching lca-api's credential policy.
+            authSchemePreference: ['sigv4'],
+            requestHandler: { requestTimeout: config.timeoutMs, connectionTimeout: 3_000 },
+        });
+        clients.set(key, client);
+    }
+
+    return client;
+};
+
+/** Test hook: drop cached SDK clients. */
+export const resetBedrockEmbeddingClients = (): void => {
+    for (const client of clients.values()) client.destroy();
+    clients.clear();
+};
+
+export const createDefaultBedrockInvoke =
+    (config: BedrockEmbeddingConfig): BedrockInvoke =>
+    async (request, options) => {
+        const response = await getClient(config).send(
+            new InvokeModelCommand({
+                modelId: request.modelId,
+                contentType: 'application/json',
+                accept: 'application/json',
+                body: request.body,
+            }),
+            { abortSignal: options.abortSignal }
+        );
+
+        return response.body;
+    };
+
+/** Embed one text with Nova 2. Exactly one InvokeModel call; throws SkillEmbeddingError. */
+export const embedTextWithBedrock = async (
+    text: string,
+    purpose: EmbeddingPurpose,
+    config: BedrockEmbeddingConfig,
+    invoke: BedrockInvoke = createDefaultBedrockInvoke(config)
+): Promise<number[]> => {
+    const value = text.trim();
+    if (!value || value.length > NOVA2_MAX_TEXT_CHARS)
+        throw new SkillEmbeddingError('invalid_input');
+
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+        const body = await Promise.race([
+            invoke(
+                {
+                    modelId: config.modelId,
+                    body: JSON.stringify(
+                        buildNovaEmbeddingRequest(value, purpose, config.dimension)
+                    ),
+                },
+                { abortSignal: controller.signal }
+            ),
+            new Promise<never>((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new SkillEmbeddingError('timeout'));
+                }, config.timeoutMs);
+            }),
+        ]);
+
+        return parseNovaEmbeddingResponse(body, config.dimension);
+    } catch (error) {
+        throw sanitizeBedrockError(error);
+    } finally {
+        clearTimeout(timer);
+    }
+};

package/src/helpers/bedrock-embedding.smoke.test.ts

@@ -0,0 +1,53 @@
+/**
+ * LC-2206 opt-in smoke test against REAL Amazon Bedrock (paid: three InvokeModel calls).
+ * Skipped unless SKILL_EMBEDDING_BEDROCK_SMOKE=true. Never enable it in CI.
+ *
+ *   SKILL_EMBEDDING_BEDROCK_SMOKE=true AWS_PROFILE=<profile> \
+ *     bunx vitest run --config vitest.config.ts src/helpers/bedrock-embedding.smoke.test.ts
+ *
+ * Uses the normal AWS credential chain (SigV4) in us-east-1 and the same request shape,
+ * purposes, dimension and normalisation as production.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+    DEFAULT_SKILL_EMBEDDING_DIMENSION,
+    DEFAULT_SKILL_EMBEDDING_REGION,
+    NOVA2_EMBEDDING_MODEL_ID,
+} from '../config/skillEmbedding';
+import { embedTextWithBedrock, type BedrockEmbeddingConfig } from './bedrock-embedding.helpers';
+
+const enabled = process.env.SKILL_EMBEDDING_BEDROCK_SMOKE === 'true';
+
+const config: BedrockEmbeddingConfig = {
+    modelId: process.env.SKILL_EMBEDDING_BEDROCK_MODEL_ID || NOVA2_EMBEDDING_MODEL_ID,
+    region: process.env.SKILL_EMBEDDING_BEDROCK_REGION || DEFAULT_SKILL_EMBEDDING_REGION,
+    dimension: Number(process.env.SKILL_EMBEDDING_DIMENSION || DEFAULT_SKILL_EMBEDDING_DIMENSION),
+    timeoutMs: 15_000,
+};
+
+const dot = (a: number[], b: number[]) =>
+    a.reduce((sum, value, index) => sum + value * (b[index] ?? 0), 0);
+
+describe.skipIf(!enabled)('Bedrock Nova 2 embeddings smoke (real AWS, opt-in)', () => {
+    it('returns unit vectors where a related skill outranks an unrelated one', async () => {
+        const query = await embedTextWithBedrock('python data analysis', 'query', config);
+        const related = await embedTextWithBedrock(
+            'Data Analysis\nAnalyse datasets with Python and statistics',
+            'index',
+            config
+        );
+        const unrelated = await embedTextWithBedrock(
+            'Customer service\nHelp customers resolve issues politely',
+            'index',
+            config
+        );
+
+        for (const vector of [query, related, unrelated]) {
+            expect(vector).toHaveLength(config.dimension);
+            expect(Math.hypot(...vector)).toBeCloseTo(1, 6);
+        }
+
+        expect(dot(query, related)).toBeGreaterThan(dot(query, unrelated));
+    }, 60_000);
+});

package/src/helpers/boost-storage.helpers.test.ts

@@ -107,6 +107,14 @@ const options = {
     integrationId: 'integration',
 } as unknown as Parameters<typeof sendBoost>[0];
 
+const deferred = () => {
+    let resolve!: () => void;
+    const promise = new Promise<void>(complete => {
+        resolve = complete;
+    });
+    return { promise, resolve };
+};
+
 describe('boost payload storage', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -167,6 +175,61 @@ describe('boost payload storage', () => {
         }
     );
 
+    it('does not overlap relationship writes that touch the same credential', async () => {
+        const first = deferred();
+        const sent = deferred();
+        const listing = deferred();
+        const contract = deferred();
+        mocks.instanceOf.mockReturnValueOnce(first.promise);
+        mocks.sent.mockReturnValueOnce(sent.promise);
+        mocks.listing.mockReturnValueOnce(listing.promise);
+        mocks.contract.mockReturnValueOnce(contract.promise);
+        const result = sendBoost(options);
+        await vi.waitFor(() => expect(mocks.instanceOf).toHaveBeenCalledOnce());
+        expect(mocks.sent).not.toHaveBeenCalled();
+        first.resolve();
+        await vi.waitFor(() => expect(mocks.sent).toHaveBeenCalledOnce());
+        expect(mocks.listing).not.toHaveBeenCalled();
+        sent.resolve();
+        await vi.waitFor(() => expect(mocks.listing).toHaveBeenCalledOnce());
+        expect(mocks.contract).not.toHaveBeenCalled();
+        listing.resolve();
+        await vi.waitFor(() => expect(mocks.contract).toHaveBeenCalledOnce());
+        expect(mocks.accept).not.toHaveBeenCalled();
+        expect(mocks.notify).not.toHaveBeenCalled();
+        contract.resolve();
+        await expect(result).resolves.toBe('lc:network:network.example/credential:stored');
+    });
+
+    it.each(['instanceOf', 'sent', 'listing', 'contract'] as const)(
+        'stops after a failed %s relationship without acceptance or notification',
+        async failed => {
+            const error = new Error('graph write failed');
+            mocks[failed].mockRejectedValueOnce(error);
+            await expect(sendBoost(options)).rejects.toBe(error);
+            const order = ['instanceOf', 'sent', 'listing', 'contract'] as const;
+            for (const later of order.slice(order.indexOf(failed) + 1)) {
+                expect(mocks[later]).not.toHaveBeenCalled();
+            }
+            expect(mocks.accept).not.toHaveBeenCalled();
+            expect(mocks.notify).not.toHaveBeenCalled();
+        }
+    );
+
+    it.each(['listing', 'another-listing', undefined])(
+        'adds explicit listing attribution only when the listing issuer does not already cover %s',
+        async listingId => {
+            const from = {
+                type: 'appStoreListing',
+                listing: { listing_id: 'listing' },
+                ownerProfile: { profileId: 'org' },
+            } as Parameters<typeof sendBoost>[0]['from'];
+            await sendBoost({ ...options, from, listingId });
+            expect(mocks.sent).toHaveBeenCalledOnce();
+            expect(mocks.listing).toHaveBeenCalledTimes(listingId === 'another-listing' ? 1 : 0);
+        }
+    );
+
     it('does not inspect template-derived fields or add a network signature', async () => {
         const credential = { ...vc, display: { backgroundColor: '#bad' } };
         await sendBoost({ ...options, credential });

package/src/helpers/boost.helpers.ts

@@ -19,6 +19,7 @@ import {
     getIssuerDisplayName,
     getIssuerOwnerProfile,
     getIssuerProfileId,
+    isAppStoreListingIssuer,
 } from '../types/issuer';
 import { trace, traceDb } from '@tracing';
 import { injectObv3AlignmentsIntoCredentialForBoost } from '@services/skills-provider/inject';
@@ -182,38 +183,42 @@ export const sendBoost = async ({
                 storeCredential(credential)
             );
 
-            const tasks = [
-                createBoostInstanceOfRelationship(credentialInstance, boost),
-                createSentCredentialRelationship(
+            // These writes share Credential/Profile/Listing nodes. Separate concurrent
+            // auto-commit transactions can deadlock on Neo4j relationship-chain locks.
+            await traceDb('createRelationships', async () => {
+                await createBoostInstanceOfRelationship(credentialInstance, boost);
+                await createSentCredentialRelationship(
                     from,
                     to,
                     credentialInstance,
                     metadata,
                     activityId,
                     integrationId
-                ),
-            ];
+                );
 
-            if (listingId) {
-                tasks.push(
-                    createListingSentCredentialRelationship(
+                // Listing issuers already create this edge inside createSentCredentialRelationship.
+                // Keep explicit attribution for profile/integration issuers or another listing.
+                if (
+                    listingId &&
+                    (!isAppStoreListingIssuer(from) || from.listing.listing_id !== listingId)
+                ) {
+                    await createListingSentCredentialRelationship(
                         listingId,
                         to,
                         credentialInstance,
                         metadata,
                         activityId,
                         integrationId
-                    )
-                );
-            }
-
-            if (contractTerms) {
-                tasks.push(
-                    createCredentialIssuedViaContractRelationship(credentialInstance, contractTerms)
-                );
-            }
+                    );
+                }
 
-            await traceDb('createRelationships', () => Promise.all(tasks));
+                if (contractTerms) {
+                    await createCredentialIssuedViaContractRelationship(
+                        credentialInstance,
+                        contractTerms
+                    );
+                }
+            });
 
             if (autoAcceptCredential) {
                 await acceptCredential(to, getCredentialUri(credentialInstance.id, domain), {

package/src/helpers/sentry.helpers.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TRPCError } from '@trpc/server';
+
+const sentry = vi.hoisted(() => ({
+    captureException: vi.fn(),
+    setHttpStatus: vi.fn(),
+}));
+
+vi.mock('@sentry/serverless', () => ({
+    captureException: sentry.captureException,
+    getActiveTransaction: () => ({ setHttpStatus: sentry.setHttpStatus }),
+}));
+vi.mock('@environment', () => ({ environment: { SENTRY_ENV: 'test' } }));
+
+import { handleTrpcError, sentryBeforeSend, shouldReportError } from './sentry.helpers';
+
+const event: Parameters<typeof sentryBeforeSend>[0] = { event_id: 'event', type: undefined };
+
+describe('sentry helpers', () => {
+    beforeEach(() => {
+        sentry.captureException.mockClear();
+        sentry.setHttpStatus.mockClear();
+    });
+
+    it('does not capture a repeated contract consent conflict', () => {
+        const error = new TRPCError({
+            code: 'CONFLICT',
+            message: "You've already consented to this contract!",
+        });
+
+        handleTrpcError({ error, ctx: {}, path: 'contracts.consentToContract' });
+
+        expect(sentry.captureException).not.toHaveBeenCalled();
+        expect(sentry.setHttpStatus).toHaveBeenCalledWith(409);
+        expect(sentryBeforeSend(event, { originalException: error })).toBeNull();
+    });
+
+    it.each(['BAD_REQUEST', 'NOT_FOUND', 'FORBIDDEN', 'CONFLICT'])(
+        'treats %s as an expected client error',
+        code => {
+            expect(shouldReportError(code)).toBe(false);
+        }
+    );
+
+    it('still captures unexpected server errors', () => {
+        const error = new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'boom' });
+
+        handleTrpcError({ error, ctx: {}, path: 'contracts.consentToContract' });
+
+        expect(sentry.captureException).toHaveBeenCalledWith(
+            error,
+            expect.objectContaining({ level: 'error' })
+        );
+        expect(sentryBeforeSend(event, { originalException: error })).toBe(event);
+    });
+});

package/src/helpers/sentry.helpers.ts

@@ -5,9 +5,10 @@ import type { TRPCError } from '@trpc/server';
 
 /**
  * Error codes that are expected/non-critical and should not be sent to Sentry.
- * These typically represent user errors or expected authentication failures.
+ * These typically represent user errors, expected authentication failures, or
+ * client-visible state conflicts such as re-consenting to the same contract.
  */
-const IGNORED_ERROR_CODES = ['BAD_REQUEST', 'NOT_FOUND', 'FORBIDDEN'];
+const IGNORED_ERROR_CODES = ['BAD_REQUEST', 'NOT_FOUND', 'FORBIDDEN', 'CONFLICT'];
 
 /**
  * Determines if an error should be reported to Sentry based on its code.
@@ -38,7 +39,7 @@ export const handleTrpcError = ({
         !(ctx as { user?: { isChallengeValid?: boolean } })?.user?.isChallengeValid;
 
     // Only capture unexpected/critical errors
-    // Filter out expected errors (BAD_REQUEST, NOT_FOUND, FORBIDDEN) and invalid challenge attempts
+    // Filter out expected errors (see IGNORED_ERROR_CODES) and invalid challenge attempts
     if (shouldReportError(error.code) && !isInvalidChallenge) {
         Sentry.captureException(error, {
             extra: { ctx, path },