Trusted Learning Context Service (Proof of Concept)

This repository contains a portable learning context proof of concept built on AWS serverless services. It demonstrates how learning credentials and related activity signals can be ingested, normalized, and turned into learner-facing context and verifiable presentations.

It supports payloads aligned to:

• Caliper
• Open Badges 3
• CLR2

Important: Hackathon Prototype, Not Production

This codebase was created during a Gates Foundation-hosted hackathon and is shared as a proof of concept. It is intended to accelerate learning and experimentation, not to serve as production-ready reference implementation.

Expect gaps in hardening areas such as:

• security and threat modeling completeness
• scalability and performance tuning
• operational maturity and support guarantees
• conformance/compliance depth across all edge cases

Who This Is For

• Developers who want to quickly run a working end-to-end demo and explore portable learning context patterns.
• Executive and program leaders who want to understand what is possible with standards-aligned context exchange without deep technical setup.

Start Here

• Slides: 1EdTech: Portable Learning Context
• Video demo: Portable Learning Context for AI

5-Minute Developer Quickstart

npm ci
npm run build
npm run dev:learner-ux

Then:

1. Configure apps/learner-ux/.env from apps/learner-ux/.env.example.
2. Point VITE_API_BASE to your deployed API endpoint.
3. Use OAuth client credentials values (VITE_API_OAUTH_*) for easiest demo authentication.

Monorepo Layout

• services/*: Lambda handlers and shared backend logic
• packages/veramo-wrapper: adapter boundary for presentation creation/verification
• apps/learner-ux: React learner + verifier demo frontend
• docs/*: local demo and deployment/operations guides

What the Prototype Includes

• API routes:
  • POST /ingest/caliper
  • POST /ingest/openbadges3
  • POST /ingest/clr2
  • GET /submissions/{submissionId}
  • GET /learners/{learnerId}/context
  • POST /presentation/create
  • POST /presentation/verify
• Backend flow:
  • ingest handler (accept + queue)
  • persist handler (validate + normalize + persist)
  • status handler (submission status lookup)
  • learner context handler (context shaping + presentation create/verify)
• Platform components:
  • DynamoDB (TrustedLearningContextCredentialTable, TrustedLearningContextEventTable, TrustedLearningContextSubmissionTable)
  • S3 raw payload bucket (for oversized payloads)
  • SQS ingest queue + DLQ
  • CloudWatch alarms + dashboard

Core Commands

npm run lint
npm run typecheck
npm test
npm run build
npm run build:learner-ux
npm run cdk:synth

Deploy (AWS CDK)

# Dev
npx cdk deploy TrustedLearningContextServiceStack-dev --context stage=dev --require-approval never

# Prod (still prototype posture unless you harden it)
npx cdk deploy TrustedLearningContextServiceStack-prod --context stage=prod --require-approval never

API Authentication (Amazon Cognito)

API routes use a Cognito-backed JWT authorizer. The stack provisions:

• a Cognito user pool
• a Cognito domain (OAuth token endpoint)
• one or more app clients (OAuth2 client credentials flow)

Default app clients:

• tlcs-ingest-app-<stage>
• tlcs-status-app-<stage>

Override app client names via CDK context:

npx cdk deploy TrustedLearningContextServiceStack-dev \
  --context stage=dev \
  --context apiClientNames=partner-a,partner-b \
  --require-approval never

After deployment, use stack outputs:

• CognitoIssuerUrl
• CognitoTokenEndpoint
• CognitoAppClientId*

Use the token in Authorization: Bearer <token>. For local demos, set VITE_API_OAUTH_* and the learner UX can mint/refresh tokens automatically.

Local Demo Guides

• Caliper payload generator/scenarios: docs/caliper-local-generator.md
• End-to-end walkthrough: docs/demo-cheatsheet.md
• Bootstrap/operations guidance: docs/bootstrap-and-operations.md

CI/CD

GitHub Actions workflows:

• .github/workflows/ci.yml
• .github/workflows/deploy-dev.yml
• .github/workflows/deploy-prod.yml

Deployment uses OIDC role assumption (no long-lived AWS keys).

Copyright and Usage Notice

Copyright (c) 1EdTech Consortium.

This proof-of-concept code is made available for non-commercial use.
If you want to use this work in a commercial product or service, please contact 1EdTech to discuss licensing and permission.