Onboarding: strongloop/loopback

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/strongloop/loopback shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 3y ago

• 24+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live strongloop/loopback repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/strongloop/loopback.

What it runs against: a local clone of strongloop/loopback — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in strongloop/loopback | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 970 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>strongloop/loopback</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of strongloop/loopback. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/strongloop/loopback.git
#   cd loopback
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of strongloop/loopback and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "strongloop/loopback(\\.git)?\\b" \\
  && ok "origin remote is strongloop/loopback" \\
  || miss "origin remote is not strongloop/loopback (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "index.js" \\
  && ok "index.js" \\
  || miss "missing critical file: index.js"
test -f "lib/loopback.js" \\
  && ok "lib/loopback.js" \\
  || miss "missing critical file: lib/loopback.js"
test -f "lib/application.js" \\
  && ok "lib/application.js" \\
  || miss "missing critical file: lib/application.js"
test -f "lib/model.js" \\
  && ok "lib/model.js" \\
  || miss "missing critical file: lib/model.js"
test -f "lib/persisted-model.js" \\
  && ok "lib/persisted-model.js" \\
  || miss "missing critical file: lib/persisted-model.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 970 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~940d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/strongloop/loopback"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

LoopBack 3 is a Node.js framework that auto-generates REST APIs from data models and connectors to multiple databases (Oracle, MySQL, PostgreSQL, MongoDB, SOAP). It provides built-in authentication, role-based access control (ACL), and mobile services without requiring hand-coded API routes. Monolithic structure: common/models/ contains built-in models (User, AccessToken, ACL, Role, Application) with .js and .json pairs defining behavior and schema. Core connectors and datasource logic delegated to loopback-datasource-juggler and loopback-connector-remote packages. Examples in example/client-server/. Grunt-based build with ESLint enforcement.

Who it's for

Backend developers building REST APIs quickly who need multi-database support, role-based security, and mobile integration. Teams using StrongLoop/IBM API Connect for enterprise integrations.

Maturity & risk

Mature but End-of-Life: released Dec 2016, v3.28.0 shows active maintenance on critical fixes, but LoopBack 3 reached EOL in Dec 2020 and no longer accepts pull requests except for IBM API Connect customers and security fixes. Test infrastructure present (nyc, mocha, karma). This is a legacy codebase—new projects should use LoopBack 4.

High risk for new projects: EOL status means no feature development or community support. Dependency chain includes legacy packages (nodemailer, bcryptjs, bluebird for Promise polyfill). Node.js >=8 requirement is outdated. Migration path exists to LoopBack 4, but reverse compatibility is not guaranteed.

Active areas of work

Repository in maintenance-only mode: recent updates are security patches (nodemailer v6.4.16) and critical bug fixes for IBM customers. No active feature development. PR template and issue templates configured but infrequently used.

Get running

git clone https://github.com/strongloop/loopback.git
cd loopback
npm install
npm test

Daily commands:

npm test                    # Run mocha + karma suite (via Gruntfile.js)
grunt eslint                # Lint with .eslintrc config
nyc grunt mocha-and-karma   # Coverage report

No dev server command—LoopBack is a library, not an app. Consumers create Express apps that require('loopback').

Map of the codebase

• index.js — Main entry point exporting the LoopBack framework API and core functionality.
• lib/loopback.js — Core LoopBack runtime initialization, data source creation, and model registration.
• lib/application.js — Application class that manages middleware, models, datasources, and request lifecycle.
• lib/model.js — Base model abstraction providing ORM capabilities and data manipulation methods.
• lib/persisted-model.js — Extends Model with persistence logic, hooks, and database query methods.
• lib/access-context.js — Authentication and authorization context tracking for ACL enforcement throughout request lifecycle.
• lib/registry.js — Central registry for models, connectors, and data sources used by the application.

How to make changes

Add a New REST API Model

1. Create model definition file in common/models/ with .js and .json pair (common/models/my-model.js)
2. Define model class extending PersistedModel with custom methods (common/models/my-model.js)
3. Add JSON schema with properties, relations, and acls (common/models/my-model.json)
4. Register model in application via app.model() during boot (lib/application.js)
5. REST endpoints auto-generated via configure-shared-methods (lib/configure-shared-methods.js)

Implement Custom Authentication

1. Extend User model in common/models/user.js with custom login method (common/models/user.js)
2. Override beforeSave hook to hash passwords with bcryptjs (common/models/user.js)
3. Create access-token factory method that returns bearer token (common/models/access-token.js)
4. Register authentication middleware in application.js (lib/application.js)

Add a Custom Data Connector

1. Create connector class extending BaseConnector (lib/connectors/base-connector.js)
2. Implement required methods: create, find, update, delete, all (lib/connectors/base-connector.js)
3. Register connector in loopback.js via Connector property (lib/loopback.js)
4. Configure datasource with connector name in application boot (lib/application.js)

Enforce Model-Level Access Control

1. Define ACL rules in model's acl property in model JSON file (common/models/my-model.json)
2. Add role mappings and principal types for users/roles (common/models/role-mapping.json)
3. Override isAuthorized() in model or use AccessContext (lib/access-context.js)
4. Middleware checks context.accessToken before executing operations (lib/application.js)

Why these technologies

• Express.js — LoopBack extends Express to provide HTTP routing and middleware layer; enables REST API auto-generation from models.
• Node.js >= 8 — Asynchronous I/O runtime required for non-blocking database and connector operations across multiple data sources.
• Async/Bluebird Promises — Manages complex async flows for hooks, validation, connector delegation, and multi-datasource queries.
• bcryptjs — Provides secure password hashing in User model to prevent plaintext password exposure.
• Body-parser — Middleware to parse incoming JSON/form request bodies for REST API payloads.

Trade-offs already made

• Model-centric architecture with auto-generated REST endpoints

  • Why: Rapid API development with minimal boilerplate for CRUD operations.
  • Consequence: Less control over endpoint implementation; harder to customize HTTP behavior for non-standard endpoints.

• Connector abstraction layer supporting multiple databases

  • Why: Enables code portability across MySQL, PostgreSQL, MongoDB, Oracle, SQL Server.
  • Consequence: Lowest-common-denominator query API; advanced DB features (stored procs, window functions) require raw SQL fallback.

• Synchronous ACL evaluation on every request

  • Why: Ensures consistent security policy enforcement without stale permission caches.
  • Consequence: ACL lookups add request latency; complex ACL graphs can become performance bottleneck.

• Built-in User/Role/ACL models baked into core

  • Why: Out-of-box auth & authorization without additional setup.
  • Consequence: Tight coupling between security model and domain models; switching auth strategy requires model overrides.

Non-goals (don't propose these)

• Not a real-time communication framework (WebSocket/Server-Sent Events require external integration).
• Not a database-agnostic query builder at the SQL level (Connector API abstracts CRUD only, not complex joins).
• Not a frontend framework (REST API only; no built-in UI or view templating).
• Does not support horizontal scaling out-of-box (no built-in session store clustering or distributed locking).
• LoopBack 3 is end-of-life; no new features accepted, only critical security fixes for API Connect customers.

Traps & gotchas

No data migration tools included—use loopback-datasource-juggler directly for schema migrations. Email service requires nodemailer config—defaults to stub transport; production needs SMTP setup in datasource config. ACL is permission-by-default: deny—must explicitly grant permissions. loopback-filters is a separate package—query filters don't work without it installed. Browser/Node.js dual support via karma—tests run in both; some polyfills (bluebird promises) expected. Strong-remoting RPC layer is opaque—method decoration and remote call marshalling happen via metadata on model.js files, not runtime inspection.

Architecture

Concepts to learn

• Model-Driven REST API Generation — LoopBack's core value—understanding how .json schemas become HTTP verbs and how .js method exports become endpoints (via strong-remoting) is essential to extending models.
• Access Control Lists (ACL) — LoopBack security model is ACL-based (not role-based by default)—understanding ALLOW/DENY scopes (model, property, method) and role matching ($owner, $authenticated, custom roles) is critical for permission bugs.
• Datasource Connectors & Adapters — LoopBack abstracts database drivers (MySQL, MongoDB, etc.) behind a Connector interface in loopback-datasource-juggler—knowing which connector to use and its quirks (e.g., MongoDB lacks SQL transactions) affects model behavior.
• Model Relationships (HasMany, BelongsTo, HasAndBelongsToMany) — Relationships are declared in model .json files but enforced at ORM level—understanding how foreign keys and joins are materialized on each connector type prevents N+1 queries and data integrity issues.
• Strong-Remoting Method Decoration & RPC Marshalling — Model methods are auto-exposed as REST endpoints via metadata (e.g., LoopBack.remoteMethod() decorators)—understanding argument serialization, middleware chains, and context binding prevents subtle bugs in API contract.
• Hooks & Model Lifecycle (beforeCreate, afterSave, etc.) — LoopBack models fire hooks at CRUD boundaries—essential for audit logs, validation, and cascading deletes without writing custom middleware.
• Context & Scope Propagation (loopback.getCurrentContext) — Async context (user identity, tenancy, tracing) flows via Node.js AsyncLocalStorage (or CLS polyfill in LoopBack 3)—critical for multi-tenant isolation and audit logging without threading context through every function.

Related repos

• strongloop/loopback-next — LoopBack 4 is the active successor—designed from scratch with TypeScript, dependency injection, and modern Node.js tooling. All new projects should target this.
• strongloop/loopback-datasource-juggler — Extracted ORM layer used by LoopBack 3—handles model definitions, relationships, and database connectors (MySQL, PostgreSQL, MongoDB, Oracle).
• strongloop/strong-remoting — RPC and HTTP marshalling layer—converts LoopBack model methods to REST endpoints with argument validation and serialization.
• strongloop/loopback-connector-remote — Connector for calling remote REST APIs as LoopBack data sources—enables federation of external services.
• expressjs/express — Foundation HTTP framework—LoopBack extends Express middleware and routing patterns.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for common/models/user.js authentication flow

The user.js model handles critical authentication logic (password hashing with bcryptjs, token generation, login/logout). Currently, there are no dedicated test files visible in the file structure for this model's core functionality. Given the security-critical nature and the presence of bcryptjs dependency, adding tests for password validation, token lifecycle, and edge cases would significantly improve code reliability and catch regressions.

• [ ] Create test/unit/models/user.test.js with mocha test suite
• [ ] Add tests for password hashing and comparison methods
• [ ] Add tests for access token generation and validation in user.js
• [ ] Test edge cases: null passwords, expired tokens, concurrent login attempts
• [ ] Integrate tests into the existing nyc coverage pipeline in package.json
• [ ] Verify test output in CI via .travis.yml

Add integration tests for ACL (access-token.js, acl.js, role.js) permission model

The common/models directory contains critical security models (access-token.js, acl.json, role.js, role-mapping.js, scope.js) that work together for authorization. There's no visible integration test suite validating the complete ACL flow (user → role → scope → access decision). This is a high-impact area for security and correctness, especially given IBM's involvement and support for API Connect customers.

• [ ] Create test/integration/acl-permissions.test.js
• [ ] Test role creation and role-mapping associations
• [ ] Test scope validation against ACL rules
• [ ] Test access token validation through the complete ACL chain
• [ ] Add tests for edge cases: missing roles, circular role hierarchies, scope conflicts
• [ ] Document test expectations in docs/testing-acl.md

Add Node.js version matrix testing in .travis.yml for supported LTS versions

The package.json specifies 'engines': {'node': '>=8'}, but .travis.yml configuration is incomplete in the provided snippet. LoopBack 3 is in LTS maintenance mode for IBM customers, but the CI doesn't explicitly test against Node.js 12.x, 14.x, and 16.x LTS versions. This causes silent breakage when dependencies upgrade and break compatibility. Adding a test matrix ensures stability for long-term support commitments.

• [ ] Update .travis.yml to test against node versions: 12, 14, 16
• [ ] Ensure nyc coverage is collected only on a single Node version to avoid redundancy
• [ ] Add node_js array with explicit versions in .travis.yml
• [ ] Test that example/ applications run successfully on all Node versions
• [ ] Update CONTRIBUTING.md to document minimum Node versions for development

Good first issues

• Add missing test files for common/models/checkpoint.js—model exists with JSON schema but appears to have minimal test coverage. Start by checking /test directory for checkpoint tests and add mocha cases for sync/changepoint operations.
• Document the role-mapping resolution order in common/models/role-mapping.js—no comments explain when built-in roles (e.g., $owner, $authenticated) are resolved vs. custom roles. Add JSDoc and update docs/role-mapping-guide.md.
• Upgrade nodemailer from v6.4.16 and verify direct-transport / stub-transport adapters still work—check for breaking changes in nodemailer API (send method signature) and update integration tests in common/models/email.js.

Top contributors

• @bajtos — 48 commits
• @dhmlau — 16 commits
• @nabdelgadir — 4 commits
• @virkt25 — 4 commits
• @jannyHou — 3 commits

Recent commits

• 13371fd — Merge pull request #4343 from achrinzafork/chore/update-lts (dhmlau)
• 1316be5 — chore: update LTS status to End-of-Life (achrinza)
• a22d4f9 — 3.28.0 (jannyHou)
• 223dd5d — Merge pull request #4338 from achrinzafork/chore/update-module-lts-node14 (dhmlau)
• fbd9783 — Merge pull request #4340 from strongloop/upgrade-nodemailer (jannyHou)
• 6f04b61 — upgrade nodemailer to greater than 6.4.16 (jannyHou)
• ab3e159 — chore: sync LoopBack 4 with Node.js v14 EOL (achrinza)
• 5b61efb — Merge pull request #4334 from strongloop/travis (dhmlau)
• e457e26 — chore: add Node.js 14 to travis (dhmlau)
• ab2e462 — Merge pull request #4318 from strongloop/bajtos-patch-1 (bajtos)

Security observations

• Critical · End of Life Framework — README.md, package.json (version 3.28.0). LoopBack 3 has reached end of life and is no longer receiving security updates or support from the maintainers. Only critical bugs and security vulnerabilities for IBM API Connect customers are addressed. This means new vulnerabilities may not be patched for general users. Fix: Migrate to LoopBack 4 or the latest version immediately. If migration is not possible, implement additional security controls and conduct regular security audits.
• High · Outdated Dependencies with Known Vulnerabilities — package.json - dependencies section. Multiple dependencies are pinned to versions from 2016-2017, including express (^4.14.0), body-parser (^1.12.0), and nodemailer (^6.4.16 but others are older). These versions likely contain known security vulnerabilities. For example, body-parser 1.12.0 is from 2015. Fix: Update all dependencies to their latest stable versions. Run 'npm audit' and address all reported vulnerabilities. Implement automated dependency scanning (Dependabot, Snyk) and regular update cycles.
• High · Node.js Version Constraint Allows Insecure Versions — package.json - engines section. Engine requirement allows Node.js >=8, which includes versions 8.x and 9.x that are no longer receiving security updates. Node.js 8.x reached end of life in December 2019. Fix: Update minimum Node.js version to at least 14.x or higher (ideally 16.x+). Update engines constraint to 'node': '>=14.0.0' or newer.
• High · bcryptjs Version Deprecated — package.json - bcryptjs dependency. bcryptjs 2.1.0 is an old version. The package may have known vulnerabilities and the maintainer has recommended using bcrypt instead for Node.js environments. Fix: Consider upgrading to bcryptjs 2.4.3+ or switch to the native 'bcrypt' package (>= 5.0.0) for better performance and security.
• Medium · Missing Security Headers Configuration — index.js, common/models (base configuration files). No visible implementation of security middleware like helmet.js which adds critical HTTP security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in the file structure. Fix: Integrate helmet.js middleware for express. Add configuration for security headers. Implement HSTS, CSP, and other protective headers.
• Medium · Email Implementation Without Validation — common/models/email.js, common/models/email.json. The codebase includes email models and nodemailer transport, but without visible input validation patterns or sanitization. Email templates (EJS) could be vulnerable to template injection if user input is passed unsafely. Fix: Ensure all email inputs are validated and sanitized. Use EJS with safety options enabled. Never pass unsanitized user input directly to template engines. Implement email address validation using the isemail dependency consistently.
• Medium · No Visible Rate Limiting or Brute Force Protection — common/models/user.js, common/models/access-token.js. No evident rate limiting, brute force protection, or request throttling in the visible file structure for authentication endpoints (access-token, user models). Fix: Implement express-rate-limit or similar middleware. Add account lockout mechanisms after failed login attempts. Implement CAPTCHA for authentication endpoints.
• Medium · Potential CSRF Protection Gap — package.json - dependencies section. While express-session is in devDependencies, there's no visible CSRF token middleware (like csurf) in the dependencies. Production CSRF protection may be missing. Fix: Add csurf or similar CSRF protection middleware. Ensure all state-changing operations (POST, PUT, DELETE) require valid CSRF tokens.
• Low · Hardcoded Transport Methods — undefined. Multiple nodemailer transport options are hardcoded (nodemailer-direct-transport, nodemailer- Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.