Implement npm remote repositories per the [S15 spec](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S15-npm-remote.md) (spec issue #282): a faithful caching proxy for a single external npm registry (typically `registry.npmjs.org`), built on the format-agnostic remote foundation S13 introduces. Covers the caching-proxy read path (packument, abbreviated packument, dist-tags, tarball), write-verb unavailability (`405 unsupported`), the streaming `dist.tarball` transform, the five `npm_remote_*` cache tables, lazy cache-fill, the npm-service-layer credential handling, and the npm-remote observability surface. S15 **composes** S13's Lookup/Probe/Fetch operations rather than defining them; it owns the npm cache schema and the one `dist.tarball` rewrite transform. The remote code extends the landed npm hosted package in `internal/format/npm/`, with the pure building blocks and operations glue in a new `internal/format/npm/npmremote/` subpackage (the `streampub` precedent) and the remote cache stores in `internal/datastore/npm_remote_*.go`. ## References - **Spec:** [S15 — npm remote](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S15-npm-remote.md) (spec issue #282) - **Plan:** [S15 npm remote implementation plan](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/2026-07-15-npm-remote.md) — merged in !944 - **Parent epic:** #22810 (Artifact Registry: Remote repositories S13–S16) - **Foundation dependency:** S13 (#280) — the Lookup/Probe/Fetch interface + stub and the security-hardened upstream HTTP client every Track B step composes. Ratified with the S13 DRI per the [development model](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/development-model.md) conciliation process. - **Spec-gap note:** the plan flags the spec's three #68 references as stale — #68 is a closed doc-guidance task, not the credential-encryption tracker. The plaintext → encrypted `tmp_plaintext_auth_token` migration anchors on [S04-A](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S04-a-column-level-encryption.md); a correct GA-blocking tracker is still to be filed. ## Steps Broken into 14 child tasks (below). **Execution order follows the dependency DAG, not the numeric step order.** Each task's `Depends on` predecessors are tracked as blocked-by links, so GitLab surfaces what is ready to start. The plan splits the work into two tracks around the S13 dependency: - **Track A — S13-independent, startable now (Steps 1–8):** the five cache tables, the `NpmConfig` field, the pure building blocks, the datastore read/write/credential layers, and the kind-dispatch seam that lands the write-verb `405`s and remote-read `501` stubs. Steps 1, 3, and 4 start from `main` with no predecessor; Steps 6/7 and 10/11/12 are sibling-parallel. - **Track B — S13-gated (Steps 9–14):** the operations glue over S13, the three proxy handlers (each flipping its own remote route from `501` to real), observability, and the conformance harness. Track B is gated on S13's interface + stub landing on `main` (#280); **Step 9 carries the formal blocked-by link to #280**, and the internal DAG transitively gates the rest of Track B behind it. ```mermaid graph TD S1["Step 1: schema - repositories/packages/versions"] S2["Step 2: schema - metadata_files/files"] S3["Step 3: NpmConfig max_remote_packument_size"] S4["Step 4: remote building blocks - transform/URL/segment safety"] S5["Step 5: datastore remote read + remote-repo finder"] S6["Step 6: datastore remote write - cache-fill"] S7["Step 7: repo service layer - credentials + cache-validity"] S8["Step 8: kind-dispatch seam + write-unavailability"] S9["Step 9: remote operations glue over S13"] S10["Step 10: packument proxy handler"] S11["Step 11: dist-tags proxy handler"] S12["Step 12: tarball proxy handler"] S13["Step 13: observability hooks"] S14["Step 14: end-to-end conformance harness"] EXT["S13 foundation (#280)"] S1 --> S2 S2 --> S5 S5 --> S6 S5 --> S7 S5 --> S8 S3 --> S9 S4 --> S9 S6 --> S9 EXT --> S9 S8 --> S10 S8 --> S11 S8 --> S12 S9 --> S10 S9 --> S11 S9 --> S12 S10 --> S13 S11 --> S13 S12 --> S13 S10 --> S14 S12 --> S14 ``` | Step | Track | Child task | Blocked by | | ---- | ----- | ---------- | ---------- | | 1 | A | #338 — schema — repositories/packages/versions | — | | 2 | A | #339 — schema — metadata_files/files | #338 | | 3 | A | #340 — NpmConfig — max_remote_packument_size | — | | 4 | A | #341 — remote building blocks — transform/URL/segment safety | — | | 5 | A | #342 — datastore remote read + remote-repo finder | #339 | | 6 | A | #343 — datastore remote write — cache-fill | #342 | | 7 | A | #344 — repo service layer — credentials + cache-validity | #342 | | 8 | A | #345 — kind-dispatch seam + write-unavailability | #342 | | 9 | B | #346 — remote operations glue over S13 | #340, #341, #343, #280 (S13) | | 10 | B | #347 — packument proxy handler | #345, #346 | | 11 | B | #348 — dist-tags proxy handler | #345, #346 | | 12 | B | #349 — tarball proxy handler | #345, #346 | | 13 | B | #350 — observability hooks | #347, #348, #349 | | 14 | B | #351 — end-to-end conformance harness | #347, #349 | Numeric IDs are stable references for the plan's Status table and review discussion. See each child task for scope, files, acceptance, and tests, and the [plan](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/2026-07-15-npm-remote.md) for the full rationale.