CNPMCore Internal API Documentation

This document provides comprehensive documentation for cnpmcore's internal APIs that allow direct HTTP requests without using the cnpm client. These APIs enable package synchronization, administration, and other advanced operations.

Authentication
Package Sync API
Binary Sync API
Token Management API
Package Block/Admin API
Registry Management API
Hook Management API
User Management API
Common Schemas

Authentication

Most internal APIs require authentication using one of these methods:

Bearer Token Authentication

curl -H "Authorization: Bearer ${TOKEN}" https://your-registry.com/api/endpoint

Admin Access

Some APIs require admin privileges. Admin users are configured in the registry settings.

Package Sync API

The package sync functionality allows you to synchronize packages from external registries (like npmjs.org) to your private registry.

Create Sync Task (Modern API)

Trigger a package synchronization task.

PUT /-/package/:fullname/syncs

Authentication

Required. Must be authenticated user.

Parameters

fullname (string): Package name (can include scope, e.g., @scope/package)

Request Body

{
  "skipDependencies": false,
  "syncDownloadData": false,
  "force": false,
  "forceSyncHistory": false,
  "tips": "Custom sync reason",
  "registryName": "optional-source-registry",
  "specificVersions": "[\"1.0.0\", \"1.0.1\"]"
}

Request Body Schema

Field	Type	Required	Description
`skipDependencies`	boolean	No	Skip syncing package dependencies
`syncDownloadData`	boolean	No	Sync download statistics data
`force`	boolean	No	Force immediate execution (admin only)
`forceSyncHistory`	boolean	No	Sync all historical versions (admin only)
`tips`	string	No	Custom reason/description for sync
`registryName`	string	No	Source registry name
`specificVersions`	string	No	JSON array of specific versions to sync

Example Request

curl -X PUT \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "skipDependencies": false,
    "syncDownloadData": false,
    "force": false,
    "tips": "Manual sync from API"
  }' \
  https://your-registry.com/-/package/lodash/syncs

Response

{
  "ok": true,
  "id": "sync-task-uuid",
  "type": "package",
  "state": "waiting"
}

Create Sync Task (Legacy API)

Legacy endpoint for compatibility with cnpmjs.org.

PUT /:fullname/sync

Parameters

fullname (string): Package name
nodeps (query): Set to "true" to skip dependencies

Example Request

curl -X PUT \
  -H "Authorization: Bearer your-token-here" \
  "https://your-registry.com/lodash/sync?nodeps=false"

Response

{
  "ok": true,
  "logId": "sync-task-uuid"
}

Get Sync Task Status

Check the status of a sync task.

GET /-/package/:fullname/syncs/:taskId

Parameters

fullname (string): Package name
taskId (string): Task ID returned from sync creation

Example Request

curl -H "Authorization: Bearer your-token-here" \
  https://your-registry.com/-/package/lodash/syncs/sync-task-uuid

Response

{
  "ok": true,
  "id": "sync-task-uuid",
  "type": "package",
  "state": "success",
  "logUrl": "https://your-registry.com/-/package/lodash/syncs/sync-task-uuid/log"
}

Task States

waiting: Task is queued
processing: Task is currently running
success: Task completed successfully
error: Task failed

Get Sync Task Log

Retrieve the log for a sync task.

GET /-/package/:fullname/syncs/:taskId/log

Parameters

fullname (string): Package name
taskId (string): Task ID

Example Request

curl -H "Authorization: Bearer your-token-here" \
  https://your-registry.com/-/package/lodash/syncs/sync-task-uuid/log

Response

Returns the log content as plain text or redirects to log URL.

Legacy Sync Status API

Legacy endpoint for checking sync status.

GET /:fullname/sync/log/:taskId

Example Request

curl -H "Authorization: Bearer your-token-here" \
  https://your-registry.com/lodash/sync/log/sync-task-uuid

Response

{
  "ok": true,
  "syncDone": true,
  "log": "[2024-01-01T12:00:00Z] [done] Sync lodash data: {...}",
  "logUrl": "https://your-registry.com/-/package/lodash/syncs/sync-task-uuid/log"
}

Binary Sync API

Manage and sync binary packages (like Node.js, Python, etc.).

List All Binaries

Get a list of all available binary packages.

GET /-/binary/

Example Request

curl https://your-registry.com/-/binary/

Response

[
  {
    "name": "node/",
    "category": "node/",
    "description": "Node.js runtime",
    "distUrl": "https://nodejs.org/dist/",
    "repoUrl": "https://github.com/nodejs/node",
    "type": "dir",
    "url": "https://your-registry.com/-/binary/node/"
  }
]

Browse Binary Directory

Browse files in a binary package directory.

GET /-/binary/:binaryName/:subpath

Parameters

binaryName (string): Binary package name (e.g., "node", "python")
subpath (string): Path within the binary directory
since (query): Filter files modified since date
limit (query): Limit number of results (max 1000)

Example Request

curl https://your-registry.com/-/binary/node/v18.0.0/

Token Management API

Manage authentication tokens for users.

Create Token

Create a new authentication token.

POST /-/npm/v1/tokens

Authentication

Required. Must provide current password.

Request Body

{
  "password": "current-password",
  "readonly": false,
  "automation": false,
  "cidr_whitelist": ["127.0.0.1", "192.168.1.0/24"]
}

Request Body Schema

Field	Type	Required	Description
`password`	string	Yes	Current user password (8-100 chars)
`readonly`	boolean	No	Create read-only token
`automation`	boolean	No	Mark token for automation use
`cidr_whitelist`	array	No	IP address restrictions (max 10)

Example Request

curl -X POST \
  -H "Authorization: Bearer existing-token" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "my-password",
    "readonly": false,
    "cidr_whitelist": ["127.0.0.1"]
  }' \
  https://your-registry.com/-/npm/v1/tokens

Response

{
  "token": "npm_xxxxxxxxxxxxxxxxxxxx",
  "key": "full-token-key-hash",
  "cidr_whitelist": ["127.0.0.1"],
  "readonly": false,
  "automation": false,
  "created": "2024-01-01T12:00:00.000Z",
  "updated": "2024-01-01T12:00:00.000Z"
}

List Tokens

Get all tokens for the authenticated user.

GET /-/npm/v1/tokens

Authentication

Required.

Example Request

curl -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/npm/v1/tokens

Response

{
  "objects": [
    {
      "token": "npm_xx...xx",
      "key": "token-key-hash",
      "cidr_whitelist": null,
      "readonly": false,
      "automation": false,
      "created": "2024-01-01T12:00:00.000Z",
      "updated": "2024-01-01T12:00:00.000Z",
      "lastUsedAt": "2024-01-01T12:30:00.000Z"
    }
  ],
  "total": 1,
  "urls": {}
}

Delete Token

Remove an authentication token.

DELETE /-/npm/v1/tokens/token/:tokenKey

Authentication

Required.

Parameters

tokenKey (string): The token key to delete

Example Request

curl -X DELETE \
  -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/npm/v1/tokens/token/token-key-hash

Response

{
  "ok": true
}

Package Block/Admin API

Administrative APIs for blocking and managing packages. Requires admin access.

Block Package

Block a package from being downloaded or published.

PUT /-/package/:fullname/blocks

Authentication

Required. Admin access only.

Parameters

fullname (string): Package name to block

Request Body

{
  "reason": "Detailed reason for blocking this package"
}

Example Request

curl -X PUT \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Package contains malicious code"
  }' \
  https://your-registry.com/-/package/malicious-package/blocks

Response

{
  "ok": true,
  "id": "block-record-id",
  "package_id": "package-internal-id"
}

Unblock Package

Remove a block from a package.

DELETE /-/package/:fullname/blocks

Authentication

Required. Admin access only.

Parameters

fullname (string): Package name to unblock

Example Request

curl -X DELETE \
  -H "Authorization: Bearer admin-token" \
  https://your-registry.com/-/package/malicious-package/blocks

Response

{
  "ok": true
}

Get Package Block Status

Check if a package is blocked and why.

GET /-/package/:fullname/blocks

Parameters

fullname (string): Package name to check

Example Request

curl https://your-registry.com/-/package/some-package/blocks

Response

{
  "blocked": true,
  "reason": "Package contains malicious code (operator: admin/admin-id)",
  "createdAt": "2024-01-01T12:00:00.000Z"
}

Registry Management API

Manage multiple npm registries and their configurations.

List Registries

Get all configured registries.

GET /-/registry

Query Parameters

pageSize (number): Results per page (1-100, default: 20)
pageIndex (number): Page number (0-based, default: 0)

Example Request

curl "https://your-registry.com/-/registry?pageSize=10&pageIndex=0"

Response

{
  "data": [
    {
      "registryId": "npmjs",
      "name": "Official NPM Registry",
      "host": "https://registry.npmjs.org",
      "type": "npm",
      "userPrefix": "npm:",
      "changeStream": "https://replicate.npmjs.com",
      "response": null
    }
  ],
  "total": 1
}

Get Registry Details

Get details for a specific registry.

GET /-/registry/:id

Parameters

id (string): Registry ID

Example Request

curl https://your-registry.com/-/registry/npmjs

Create Registry

Create a new registry configuration.

POST /-/registry

Authentication

Required. Admin access only.

Request Body

{
  "name": "Custom Registry",
  "host": "https://my-custom-registry.com",
  "changeStream": "https://my-custom-registry.com/_changes",
  "type": "cnpm"
}

Example Request

curl -X POST \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Registry",
    "host": "https://my-custom-registry.com",
    "type": "cnpm"
  }' \
  https://your-registry.com/-/registry

Hook Management API

Manage webhooks that trigger on package events (publish, install, etc.).

Base Path: All hook endpoints use the base path /-/npm

Create Hook

Create a new webhook.

POST /-/npm/v1/hooks/hook

Authentication

Required.

Request Body

{
  "type": "package",
  "name": "hook-name",
  "endpoint": "https://your-webhook-endpoint.com/hook",
  "secret": "webhook-secret-key"
}

Request Body Schema

Field	Type	Required	Description
`type`	string	Yes	Hook type (e.g., "package")
`name`	string	Yes	Hook name (1-428 chars)
`endpoint`	string	Yes	Webhook URL (1-2048 chars)
`secret`	string	Yes	Secret key for webhook verification (1-200 chars)

Example Request

curl -X POST \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "package",
    "name": "my-webhook",
    "endpoint": "https://my-server.com/webhook",
    "secret": "my-secret-key"
  }' \
  https://your-registry.com/-/npm/v1/hooks/hook

Response

{
  "id": "hook-uuid",
  "name": "my-webhook",
  "type": "package",
  "endpoint": "https://my-server.com/webhook",
  "created": "2024-01-01T12:00:00.000Z",
  "updated": "2024-01-01T12:00:00.000Z",
  "delivered": false,
  "last_delivery": null
}

Update Hook

Update an existing webhook.

PUT /-/npm/v1/hooks/hook/:id

Authentication

Required. Must be hook owner.

Parameters

id (string): Hook ID

Request Body

{
  "endpoint": "https://new-webhook-endpoint.com/hook",
  "secret": "new-secret-key"
}

Example Request

curl -X PUT \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://updated-server.com/webhook",
    "secret": "updated-secret"
  }' \
  https://your-registry.com/-/npm/v1/hooks/hook/hook-uuid

Delete Hook

Remove a webhook.

DELETE /-/npm/v1/hooks/hook/:id

Authentication

Required. Must be hook owner.

Parameters

id (string): Hook ID

Example Request

curl -X DELETE \
  -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/npm/v1/hooks/hook/hook-uuid

Response

{
  "id": "hook-uuid",
  "name": "my-webhook",
  "type": "package",
  "endpoint": "https://my-server.com/webhook",
  "created": "2024-01-01T12:00:00.000Z",
  "updated": "2024-01-01T12:00:00.000Z",
  "deleted": "2024-01-01T13:00:00.000Z"
}

List Hooks

Get all hooks for the authenticated user.

GET /-/npm/v1/hooks

Authentication

Required.

Example Request

curl -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/npm/v1/hooks

Response

{
  "objects": [
    {
      "id": "hook-uuid",
      "name": "my-webhook",
      "type": "package",
      "endpoint": "https://my-server.com/webhook",
      "created": "2024-01-01T12:00:00.000Z",
      "updated": "2024-01-01T12:00:00.000Z",
      "delivered": true,
      "last_delivery": "2024-01-01T12:30:00.000Z"
    }
  ]
}

Get Hook Details

Get details for a specific hook.

GET /-/npm/v1/hooks/hook/:id

Authentication

Required. Must be hook owner.

Parameters

id (string): Hook ID

Example Request

curl -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/npm/v1/hooks/hook/hook-uuid

User Management API

Manage user accounts and authentication.

Create User / Login

Create a new user account or login existing user.

PUT /-/user/org.couchdb.user::username

Parameters

username (string): Username to create/login

Request Body

{
  "_id": "org.couchdb.user:username",
  "name": "username",
  "password": "user-password",
  "email": "[email protected]",
  "type": "user",
  "roles": [],
  "date": "2024-01-01T12:00:00.000Z"
}

Request Body Schema

Field	Type	Required	Description
`_id`	string	Yes	Must be "org.couchdb.user:" + username
`name`	string	Yes	Username (1-100 chars)
`password`	string	Yes	Password (8-100 chars)
`email`	string	No	Email address (valid email format)
`type`	string	Yes	Must be "user"
`roles`	array	No	User roles (usually empty)
`date`	string	No	Registration date

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "org.couchdb.user:johndoe",
    "name": "johndoe",
    "password": "securepassword123",
    "email": "[email protected]",
    "type": "user",
    "roles": []
  }' \
  https://your-registry.com/-/user/org.couchdb.user:johndoe

Response (Success - New User)

{
  "ok": true,
  "id": "org.couchdb.user:johndoe",
  "rev": "1-hash",
  "token": "user-token-uuid"
}

Response (Success - Login)

{
  "ok": true,
  "id": "org.couchdb.user:johndoe",
  "rev": "existing-rev-hash",
  "token": "user-token-uuid"
}

Error Responses

401 Unauthorized: Wrong password for existing user
403 Forbidden: Public registration disabled
409 Conflict: User exists but email differs
422 Unprocessable Entity: Username mismatch in URL/body

Common Schemas

Error Response

All APIs return errors in a consistent format:

{
  "error": "error_code",
  "reason": "Human readable error message"
}

Common HTTP Status Codes

200 OK: Request successful
201 Created: Resource created successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required or invalid
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
409 Conflict: Resource already exists
500 Internal Server Error: Server error

Package Naming

Package names follow npm naming conventions:

Unscoped: package-name
Scoped: @scope/package-name
Must match regex: ^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$

Examples

Complete Sync Workflow

Trigger sync for a package:

curl -X PUT \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"tips": "API sync request"}' \
  https://your-registry.com/-/package/lodash/syncs

Check sync status:

curl -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/package/lodash/syncs/task-id

View sync logs:

curl -H "Authorization: Bearer your-token" \
  https://your-registry.com/-/package/lodash/syncs/task-id/log

Batch Operations

For multiple packages, send individual requests or implement your own batch processing script using these APIs.

Error Handling

Always check the HTTP status code and response body for errors:

response=$(curl -s -w "%{http_code}" -H "Authorization: Bearer token" \
  https://your-registry.com/-/package/nonexistent/syncs)
http_code=$(echo "$response" | tail -c 4)
body=$(echo "$response" | sed 's/...$//')

if [ "$http_code" -ne 201 ]; then
  echo "Error: $body"
  exit 1
fi

Rate Limiting

Be mindful of rate limits when making multiple API requests. Consider implementing:

Delays between requests
Exponential backoff for retries
Concurrent request limits

Security Considerations

Always use HTTPS in production
Store tokens securely and rotate them regularly
Use read-only tokens when possible
Implement IP whitelisting for sensitive operations
Monitor API usage for unusual patterns

For more information about cnpmcore, visit the official documentation.

FilesExpand file tree

internal-api.md

Latest commit

History

internal-api.md

File metadata and controls

CNPMCore Internal API Documentation

Table of Contents

Authentication

Bearer Token Authentication

Admin Access

Package Sync API

Create Sync Task (Modern API)

Authentication

Parameters

Request Body

Request Body Schema

Example Request

Response

Create Sync Task (Legacy API)

Parameters

Example Request

Response

Get Sync Task Status

Parameters

Example Request

Response

Task States

Get Sync Task Log

Parameters

Example Request

Response

Legacy Sync Status API

Example Request

Response

Binary Sync API

List All Binaries

Example Request

Response

Browse Binary Directory

Parameters

Example Request

Token Management API

Create Token

Authentication

Request Body

Request Body Schema

Example Request

Response

List Tokens

Authentication

Example Request

Response

Delete Token

Authentication

Parameters

Example Request

Response

Package Block/Admin API

Block Package

Authentication

Parameters

Request Body

Example Request

Response

Unblock Package

Authentication

Parameters

Example Request

Response

Get Package Block Status

Parameters

Example Request

Response

Registry Management API

List Registries

Query Parameters

Example Request

Response

Get Registry Details