Deployment & Distribution

This guide covers how to package, distribute, and deploy Authrim plugins.

Distribution Methods

Method	Target	Characteristics
npm package	Public plugins	Version management, dependency resolution
Monorepo built-in	Official plugins	Released with Authrim
Private npm	Enterprise plugins	npm mechanisms while staying private
Local files	Development/testing	Most flexible

npm Package Structure

Recommended package.json

{
  "name": "@your-org/authrim-plugin-example",
  "version": "1.0.0",
  "description": "Example plugin for Authrim",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "test": "vitest",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "@authrim/ar-lib-plugin": "^1.0.0",
    "zod": "^3.0.0"
  },
  "devDependencies": {
    "@authrim/ar-lib-plugin": "^1.0.0",
    "tsup": "^8.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0",
    "zod": "^3.0.0"
  },
  "keywords": [
    "authrim",
    "authrim-plugin",
    "authentication",
    "notification"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/authrim-plugin-example"
  }
}

Project Structure

authrim-plugin-example/
├── src/
│   ├── index.ts        # Plugin export
│   ├── handler.ts      # Handler implementation
│   └── config.ts       # Configuration schema
├── test/
│   ├── index.test.ts
│   └── handler.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── README.md
└── LICENSE

Export Pattern

src/index.ts

export { myPlugin } from './plugin';
export type { MyPluginConfig } from './config';

// Default export for convenience
export { myPlugin as default } from './plugin';

Official Plugin Criteria

Condition	Determination	Trust Level
Built into ar-lib-plugin/builtin/	Official	official
npm @authrim/* scope	Official	official
Other sources	Community	community

Important

• The official: true flag in metadata is UI supplementary information only
• author.name: 'Authrim' is self-declared and not verified
• Official status is determined only by distribution source

Versioning

Follow Semantic Versioning:

Major.Minor.Patch (e.g., 1.5.2)
   │       │      └── Bug fixes (backwards compatible)
   │       └────────── New features (backwards compatible)
   └────────────────── Breaking changes

Plugin Version in Metadata

export const myPlugin: AuthrimPlugin<Config> = {
  id: 'my-plugin',
  version: '1.0.0',  // Keep in sync with package.json
  // ...
};

Compatibility Declaration

Declare Authrim version compatibility in metadata:

meta: {
  name: 'My Plugin',
  description: '...',
  category: 'notification',

  // Compatibility
  minAuthrimVersion: '1.0.0',     // Required minimum
  maxAuthrimVersion: '1.999.999', // Optional maximum (usually set on major bump)
}

Compatibility Check Behavior

State	Level	Behavior
Older than minAuthrimVersion	Warning	Log output, continues
Newer than maxAuthrimVersion	Warning	Log output, continues
stability: 'deprecated'	Warning	Deprecation warning
stability: 'alpha' in production	Warning	Production warning

By default, only warnings are issued and plugin loading continues. This accounts for cases where declarations may be overly conservative.

Environment Variable Control

# Compatibility check level
PLUGIN_COMPATIBILITY_CHECK=warn   # Default: warn and continue
PLUGIN_COMPATIBILITY_CHECK=error  # Stop on incompatibility
PLUGIN_COMPATIBILITY_CHECK=ignore # Skip all checks

Built-in Registration

Built-in plugin metadata is registered into the plugin registry KV so the Admin UI and Plugin Management API can discover it:

import { registerBuiltinPlugins } from '@authrim/ar-lib-plugin';

await registerBuiltinPlugins(env.SETTINGS);

The current built-in registration set is the notifier plugins exported by ar-lib-plugin: notifier-console, notifier-cloudflare, and notifier-resend.

Runtime loading is configured separately in the Worker through the plugin context loader:

import { createPluginLoader, pluginContextMiddleware } from '@authrim/ar-lib-core';
import { cloudflareEmailPlugin, resendEmailPlugin } from '@authrim/ar-lib-plugin';

app.use(
  '*',
  pluginContextMiddleware({
    loadPlugins: createPluginLoader([
      { plugin: cloudflareEmailPlugin },
      { plugin: resendEmailPlugin },
    ]),
  })
);

npm Plugin Installation

For community plugins distributed via npm:

1. Install the plugin package:

   pnpm add @your-org/authrim-plugin-example

2. Register in your worker initialization:

   import { examplePlugin } from '@your-org/authrim-plugin-example';
   
   // In worker init
   await loader.loadPlugin(examplePlugin, ctx, config);

3. Add it to the runtime plugin loader and configure it via Admin API or environment variables

Local Development

For development and testing:

// Import from local path
import { myPlugin } from './plugins/my-plugin';

// Register during initialization
await loader.loadPlugin(myPlugin, ctx, {
  apiKey: 'test-key',
  endpoint: 'http://localhost:3000',
});

Publishing Checklist

Before publishing your plugin:

• Tests pass: npm test
• Types compile: npm run build
• README complete: Installation, configuration, examples
• License file: Include appropriate license (MIT recommended)
• Changelog: Document changes between versions
• Peer dependencies: Declare @authrim/ar-lib-plugin and zod
• Keywords: Include authrim and authrim-plugin
• Metadata complete: All required fields in meta

README Template

# Authrim Plugin: Example

Example notification plugin for Authrim.

## Installation

\`\`\`bash
pnpm add @your-org/authrim-plugin-example
\`\`\`

## Configuration

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `apiKey` | string | Yes | - | Your API key |
| `endpoint` | string | No | `https://api.example.com` | API endpoint |
| `timeout` | number | No | `10000` | Request timeout (ms) |

### Environment Variables

\`\`\`bash
PLUGIN_EXAMPLE_CONFIG='{"apiKey":"your-key"}'
\`\`\`

### Admin API

\`\`\`bash
curl -X PUT "/api/admin/plugins/example/config" \
  -H "Authorization: Bearer {token}" \
  -d '{"config": {"apiKey": "your-key"}}'
\`\`\`

## Usage

This plugin provides the `notifier.example` capability.

## License

MIT

Security Considerations

For Plugin Authors

1. Never log secrets: Don’t log API keys or tokens
2. Validate URLs: Prevent SSRF attacks
3. Set timeouts: Prevent resource exhaustion
4. Handle errors: Return structured errors, don’t throw
5. Audit dependencies: Review and update regularly

For Plugin Users

Before installing a plugin:

1. Author trustworthiness: Who developed it?
2. Source code review: Review if possible
3. Dependencies audit: Check for suspicious packages
4. Activity check: Is it maintained?

Authrim Does NOT Provide

• Plugin security audits
• Vulnerability scanning
• Malicious plugin detection

Use community plugins at your own risk.

Update Notifications

npm Plugins

• Version information displayed in Admin UI
• New version availability shown as reference
• Update decisions are the user’s responsibility

Local/Private Plugins

• Only version string displayed
• No automatic update notification

Next Steps

• Admin UI Management - Managing plugins through the console
• Plugin Management API - API reference for plugin operations