@learncard/learn-cloud-service 2.5.35 → 2.5.37

package/.env.example

@@ -1,36 +1,35 @@
-# LearnCloud service environment
-# Copy to .env. Validation runs before database/client initialization.
+# LearnCloud: copy to .env. Values below are disposable local examples, not deploy secrets.
+# Public configuration lives in config/config.json and config/config.<stage>.json.
+# Precedence: schema defaults < base < stage < Lambda runtime bundle < non-empty real env.
+# CONFIG_STAGE=dev or production opts local/Docker/offline into checked-in stage settings.
+# Without CONFIG_STAGE, keep using local env and schema defaults as before.
+# Lambda selects LAMBDA_STAGE; the bundle is learn-cloud-service/<stage>/runtime-secrets.
+# Leave RUNTIME_SECRETS_ID unset locally. Keep GitHub fallbacks for rollback.
+CONFIG_STAGE=
+RUNTIME_SECRETS_ID=
 
-NODE_ENV=development
-PORT=3000
+# Required credentials: replace every example before connecting to shared services.
 LEARN_CLOUD_SEED=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 LEARN_CLOUD_MONGO_URI=mongodb://localhost:27017
 LEARN_CLOUD_MONGO_DB_NAME=learncloud
-DOMAIN_NAME=
-SERVER_URL=http://localhost:4100
-XAPI_ENDPOINT=
 
+# Optional runtime credentials, including the private xAPI endpoint.
+XAPI_ENDPOINT=
+XAPI_USERNAME=
+XAPI_PASSWORD=
+JWT_SIGNING_KEY=
+SENTRY_DSN=
 # Configure both RSA values or leave both empty to generate an ephemeral pair.
 RSA_PRIVATE_KEY=
 RSA_PUBLIC_KEY=
 
+# Local infrastructure. Explicit env wins over a selected stage.
+NODE_ENV=development
+IS_OFFLINE=true
+PORT=3000
 REDIS_HOST=
 REDIS_PORT=
-SENTRY_DSN=
-SENTRY_ENV=development
-IS_OFFLINE=false
-SKIP_DIDKIT_NAPI=false
-CI=false
-
-# LC-2187 service-only share-content routes start with valid service configuration.
-# All four values are required and REDIS_HOST/REDIS_PORT must point at the real
-# replay store. Real values are provisioned per environment, never committed.
-# LearnCloud's own service DID that service tokens must address.
-SHARE_CONTENT_AUDIENCE=
-# Comma-separated allowlisted Brain service DIDs.
-SHARE_CONTENT_SERVICE_DIDS=
-# Comma-separated exact JWS `kid` verification methods (DID URL with fragment).
-SHARE_CONTENT_VERIFICATION_METHODS=
-# JSON object mapping each service DID to the namespaces it may use, e.g.
-# {"did:web:brain.example":["learncard"]}
-SHARE_CONTENT_NAMESPACE_BINDINGS=
+# Local URL override, if needed: SERVER_URL=http://localhost:4100.
+# SENTRY_ENV and SHARE_CONTENT_* trust settings come from the selected stage.
+# Self-hosters can register config/config.example.json as their own stage or use explicit env.
+# SENTRY_AUTH_TOKEN / SENTRY_ORG / SENTRY_PROJECT belong only in the build environment.

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @learncard/network-brain-service
 
+## 2.5.37
+
+### Patch Changes
+
+- [#1711](https://github.com/learningeconomy/LearnCard/pull/1711) [`63ded61d2b1b81ce1c8ad7b9415510da5e4c24ae`](https://github.com/learningeconomy/LearnCard/commit/63ded61d2b1b81ce1c8ad7b9415510da5e4c24ae) Thanks [@goblincore](https://github.com/goblincore)! - Exclude bundled service configuration from published service dependencies so public packages do not require the private service-config workspace package during installation. Keep runtime workspace dependencies for source-based service deployments.
+
+## 2.5.36
+
+### Patch Changes
+
+- [#1670](https://github.com/learningeconomy/LearnCard/pull/1670) [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2) Thanks [@Custard7](https://github.com/Custard7)! - Adopt the shared service-config model: load checked-in non-secret per-stage configuration before environment validation, bootstrap every Lambda entrypoint through the shared lazy loader, and deliver runtime secrets through an optional AWS Secrets Manager bundle with a per-value fallback for stages without one.
+
+- [#1670](https://github.com/learningeconomy/LearnCard/pull/1670) [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2) Thanks [@Custard7](https://github.com/Custard7)! - Select backend stage files by tenant as well as stage. `CONFIG_TENANT=scouts` loads `config.scouts.<stage>.json` (generated from the live ScoutPass Lambdas), so ScoutPass deployments no longer inherit LearnCard domains, trust settings or seed-encryption flags; a named tenant without a stage file fails closed. `ESCROW_ENCLAVE_MODE` is now forwarded in runtime-secrets bundle mode too.
+
+- Updated dependencies [[`6209da80c52ac056a7644dab14669192740c9dad`](https://github.com/learningeconomy/LearnCard/commit/6209da80c52ac056a7644dab14669192740c9dad), [`5890451789b18afee45dc5ecbab3fa30aa90f085`](https://github.com/learningeconomy/LearnCard/commit/5890451789b18afee45dc5ecbab3fa30aa90f085), [`1387cd0a08fa6b0a706c86a5a0376b6c7d706856`](https://github.com/learningeconomy/LearnCard/commit/1387cd0a08fa6b0a706c86a5a0376b6c7d706856), [`d7ca528898d988c65f0dc7084cfdcd41767648c5`](https://github.com/learningeconomy/LearnCard/commit/d7ca528898d988c65f0dc7084cfdcd41767648c5), [`8f3bc66ab3d3e5e1edb3fbf5f362025875a914ba`](https://github.com/learningeconomy/LearnCard/commit/8f3bc66ab3d3e5e1edb3fbf5f362025875a914ba), [`1387cd0a08fa6b0a706c86a5a0376b6c7d706856`](https://github.com/learningeconomy/LearnCard/commit/1387cd0a08fa6b0a706c86a5a0376b6c7d706856), [`267cf40291b3a63caf178857be0e57feaf5e0948`](https://github.com/learningeconomy/LearnCard/commit/267cf40291b3a63caf178857be0e57feaf5e0948), [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2), [`c78c982f9f4911f1ca2973380f19d80db775e012`](https://github.com/learningeconomy/LearnCard/commit/c78c982f9f4911f1ca2973380f19d80db775e012), [`590adf48867d6c6fd504e66a11c9827d5102122d`](https://github.com/learningeconomy/LearnCard/commit/590adf48867d6c6fd504e66a11c9827d5102122d)]:
+    - @learncard/types@5.23.0
+    - @learncard/service-config@0.1.1
+    - @learncard/didkit-plugin@1.10.3
+    - @learncard/core@9.4.38
+    - @learncard/helpers@1.6.2
+    - @learncard/did-web-plugin@1.1.38
+    - @learncard/didkey-plugin@1.1.38
+    - @learncard/didkit-plugin-node@0.3.3
+    - @learncard/encryption-plugin@1.1.38
+    - @learncard/learn-card-plugin@1.2.38
+    - @learncard/vc-plugin@1.6.4
+    - @learncard/vc-templates-plugin@1.1.38
+    - @learncard/crypto-plugin@1.1.38
+    - @learncard/expiration-plugin@1.2.38
+
 ## 2.5.35
 
 ### Patch Changes

package/bootstrapLambda.test.ts

@@ -0,0 +1,68 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
+
+const HANDLERS = ['trpcHandler', 'openApiHandler', 'shareContentHandler', 'swaggerUiHandler'];
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./lambdaApp', () => Object.fromEntries(HANDLERS.map(name => [name, mocks.handler])));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+});
+
+it('bootstraps the API once with checked-in stage config', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'learn-cloud-service-dev-trpc');
+    vi.stubEnv('LAMBDA_STAGE', 'dev');
+    await import('./lambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'dev',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('uses CONFIG_STAGE outside Lambda rather than LAMBDA_STAGE', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', '');
+    vi.stubEnv('LAMBDA_STAGE', 'production');
+    vi.stubEnv('CONFIG_STAGE', 'dev');
+    await import('./lambda');
+    expect(mocks.bootstrap).toHaveBeenCalledWith(expect.objectContaining({ stage: 'dev' }));
+    vi.unstubAllEnvs();
+});
+
+it('forces no deployed stage when serverless-offline sets a function name with an empty LAMBDA_STAGE', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'learn-cloud-service-dev-trpc');
+    vi.stubEnv('LAMBDA_STAGE', '');
+    vi.stubEnv('CONFIG_STAGE', '');
+    await import('./lambda');
+    expect(mocks.bootstrap).toHaveBeenCalledWith(expect.objectContaining({ stage: '' }));
+    vi.unstubAllEnvs();
+});
+
+it('forwards every handler through its bootstrap accessor', async () => {
+    mocks.getApp.mockResolvedValue(Object.fromEntries(HANDLERS.map(name => [name, mocks.handler])));
+    const lambda = await import('./lambda');
+    const event = {} as APIGatewayProxyEventV2;
+    const context = {} as Context;
+    const callback = vi.fn();
+    const handlers = [
+        lambda.trpcHandler,
+        lambda.openApiHandler,
+        lambda.shareContentHandler,
+        lambda.swaggerUiHandler,
+    ];
+    for (const handler of handlers) await handler(event, context, callback);
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.getApp).toHaveBeenCalledTimes(handlers.length);
+    expect(mocks.handler).toHaveBeenCalledTimes(handlers.length);
+    expect(mocks.handler).toHaveBeenCalledWith(event, context, callback);
+});

package/bundle.mjs

@@ -1,3 +1,5 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { build } from 'esbuild';
 import plugins from './esbuildPlugins.cjs';
 
@@ -9,6 +11,7 @@ const finalBuildObj = {
     entryPoints: ['src/index.ts'],
     platform: 'node',
     bundle: true,
+    metafile: true,
     format: 'cjs',
     outdir: 'dist',
     target: 'node18',
@@ -22,6 +25,11 @@ if (process.env.NODE_ENV !== 'production') {
     finalBuildObj.minify = false;
 }
 
-await build(finalBuildObj).then(() => {
+await build(finalBuildObj).then(result => {
+    // Publish preparation verifies private helpers are not external runtime imports.
+    writeFileSync(
+        join(finalBuildObj.outdir, 'publish-metafile.json'),
+        JSON.stringify(result.metafile)
+    );
     console.log(`🎁 Done building main bundle! (${Date.now() - startTime}ms)`);
 });

package/config/config.dev.json

@@ -0,0 +1,8 @@
+{
+    "SENTRY_ENV": "learn-cloud-staging",
+    "SERVER_URL": "https://staging.cloud.learncard.com",
+    "SHARE_CONTENT_AUDIENCE": "did:web:staging.cloud.learncard.com",
+    "SHARE_CONTENT_NAMESPACE_BINDINGS": "{\"did:web:staging.network.learncard.com\":[\"learncard\"]}",
+    "SHARE_CONTENT_SERVICE_DIDS": "did:web:staging.network.learncard.com",
+    "SHARE_CONTENT_VERIFICATION_METHODS": "did:web:staging.network.learncard.com#owner"
+}

package/config/config.example.json

@@ -0,0 +1,8 @@
+{
+    "SENTRY_ENV": "learn-cloud-example",
+    "SERVER_URL": "https://cloud.example.com",
+    "SHARE_CONTENT_AUDIENCE": "did:web:cloud.example.com",
+    "SHARE_CONTENT_NAMESPACE_BINDINGS": "{\"did:web:network.example.com\":[\"learncard\"]}",
+    "SHARE_CONTENT_SERVICE_DIDS": "did:web:network.example.com",
+    "SHARE_CONTENT_VERIFICATION_METHODS": "did:web:network.example.com#owner"
+}

package/config/config.json

@@ -0,0 +1 @@
+{}

package/config/config.production.json

@@ -0,0 +1,8 @@
+{
+    "SENTRY_ENV": "learn-cloud-production",
+    "SERVER_URL": "https://cloud.learncard.com",
+    "SHARE_CONTENT_AUDIENCE": "did:web:cloud.learncard.com",
+    "SHARE_CONTENT_NAMESPACE_BINDINGS": "{\"did:web:network.learncard.com\":[\"learncard\"]}",
+    "SHARE_CONTENT_SERVICE_DIDS": "did:web:network.learncard.com",
+    "SHARE_CONTENT_VERIFICATION_METHODS": "did:web:network.learncard.com#owner"
+}

package/config/config.scouts.dev.json

@@ -0,0 +1,3 @@
+{
+    "SENTRY_ENV": "scouts-learn-cloud-staging"
+}

package/config/config.scouts.production.json

@@ -0,0 +1,4 @@
+{
+    "SENTRY_ENV": "scouts-learn-cloud-production",
+    "SERVER_URL": "https://cloud.learncard.com"
+}

package/didWebLambda.test.ts

@@ -0,0 +1,41 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./didWebLambdaApp', () => ({ didWebHandler: mocks.handler }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.getApp.mockResolvedValue({ didWebHandler: mocks.handler });
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+});
+
+it('bootstraps the didWeb app with checked-in stage config and the deploy stage', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'learn-cloud-service-production-didWeb');
+    vi.stubEnv('LAMBDA_STAGE', 'production');
+    await import('./didWebLambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'production',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('resolves the app once per cold start and forwards every argument', async () => {
+    const { didWebHandler } = await import('./didWebLambda');
+    const event = {} as APIGatewayProxyEventV2;
+    const context = {} as Context;
+    const callback = vi.fn();
+    await didWebHandler(event, context, callback);
+    await didWebHandler(event, context, callback);
+    expect(mocks.getApp).toHaveBeenCalledTimes(2);
+    expect(mocks.handler).toHaveBeenLastCalledWith(event, context, callback);
+});

package/didWebLambda.ts

@@ -1,23 +1,17 @@
-import serverlessHttp from 'serverless-http';
-import * as Sentry from '@sentry/serverless';
+import { bootstrapLambda } from '@learncard/service-config';
 
-import didWebApp from './src/dids';
-import { environment } from './src/config/environment';
-import { toServerlessApplication } from './src/helpers/serverlessApplication';
+import { base, stages } from './src/config/stageConfig';
 
-Sentry.AWSLambda.init({
-    dsn: environment.SENTRY_DSN,
-    environment: environment.SENTRY_ENV,
-    enabled: Boolean(environment.SENTRY_DSN),
-    tracesSampleRate: 1.0,
-    integrations: [
-        new Sentry.Integrations.Console(),
-        new Sentry.Integrations.Http(),
-        new Sentry.Integrations.ContextLines(),
-        new Sentry.Integrations.Mongo(),
-    ],
+type DidWebApp = typeof import('./didWebLambdaApp');
+
+const getApplication = bootstrapLambda<DidWebApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./didWebLambdaApp'),
 });
 
-export const didWebHandler = Sentry.AWSLambda.wrapHandler(
-    serverlessHttp(toServerlessApplication(didWebApp))
-);
+export const didWebHandler = async (...args: Parameters<DidWebApp['didWebHandler']>) =>
+    (await getApplication()).didWebHandler(...args);

package/didWebLambdaApp.ts

@@ -0,0 +1,23 @@
+import serverlessHttp from 'serverless-http';
+import * as Sentry from '@sentry/serverless';
+
+import didWebApp from './src/dids';
+import { environment } from './src/config/environment';
+import { toServerlessApplication } from './src/helpers/serverlessApplication';
+
+Sentry.AWSLambda.init({
+    dsn: environment.SENTRY_DSN,
+    environment: environment.SENTRY_ENV,
+    enabled: Boolean(environment.SENTRY_DSN),
+    tracesSampleRate: 1.0,
+    integrations: [
+        new Sentry.Integrations.Console(),
+        new Sentry.Integrations.Http(),
+        new Sentry.Integrations.ContextLines(),
+        new Sentry.Integrations.Mongo(),
+    ],
+});
+
+export const didWebHandler = Sentry.AWSLambda.wrapHandler(
+    serverlessHttp(toServerlessApplication(didWebApp))
+);

package/dist/config/applyDockerStageConfig.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=applyDockerStageConfig.d.ts.map

package/dist/config/applyDockerStageConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyDockerStageConfig.d.ts","sourceRoot":"","sources":["../../src/config/applyDockerStageConfig.ts"],"names":[],"mappings":""}

package/dist/config/serverlessFunctionEnv.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=serverlessFunctionEnv.test.d.ts.map

package/dist/config/serverlessFunctionEnv.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverlessFunctionEnv.test.d.ts","sourceRoot":"","sources":["../../src/config/serverlessFunctionEnv.test.ts"],"names":[],"mappings":""}

package/dist/config/stageConfig.d.ts

@@ -0,0 +1,10 @@
+import 'dotenv/config';
+export declare const base: Record<string, string>;
+export declare const stages: {
+    dev: any;
+    production: any;
+    'scouts.dev': any;
+    'scouts.production': any;
+};
+export declare const applyLearnCloudStageConfig: (stage: string | undefined) => void;
+//# sourceMappingURL=stageConfig.d.ts.map

package/dist/config/stageConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stageConfig.d.ts","sourceRoot":"","sources":["../../src/config/stageConfig.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AASvB,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAc,CAAC;AAEvD,eAAO,MAAM,MAAM;;;;;CAM+B,CAAC;AAInD,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,IAEtE,CAAC"}

package/dist/config/stageConfig.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stageConfig.test.d.ts.map

package/dist/config/stageConfig.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stageConfig.test.d.ts","sourceRoot":"","sources":["../../src/config/stageConfig.test.ts"],"names":[],"mappings":""}

package/dist/docker-entry.d.ts

@@ -1,2 +1,2 @@
-export {};
+import './config/applyDockerStageConfig';
 //# sourceMappingURL=docker-entry.d.ts.map

package/dist/docker-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docker-entry.d.ts","sourceRoot":"","sources":["../src/docker-entry.ts"],"names":[],"mappings":""}
+{"version":3,"file":"docker-entry.d.ts","sourceRoot":"","sources":["../src/docker-entry.ts"],"names":[],"mappings":"AAAA,OAAO,iCAAiC,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/index.js
-size: 53395239 bytes
-sha256: 8ebe2243c876780364a730330d6e9b013db922136ba371b2bbc02af8d79d579d
+size: 53503108 bytes
+sha256: cebd208721ceb4d62ef64d1457a4a4735653aa48a7b6aeca358afcdfc267b355