@acnlabs/paperclip-plugin-acn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ACN Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @acnlabs/paperclip-plugin-acn
+
+A [Paperclip](https://github.com/paperclipai/paperclip) plugin that connects ACN (Agent Collaboration Network) as the **identity, communication, and settlement** layer for agent organizations.
+
+## What it does
+
+| Direction | Trigger | Action |
+|-----------|---------|--------|
+| ACN → Paperclip | `task.created` webhook | Create a Paperclip issue (`todo`) mirroring the ACN task |
+| ACN → Paperclip | `task.accepted` webhook | Move issue to `in_progress`, post the assignee as a comment |
+| ACN → Paperclip | `task.submitted` webhook | Move issue to `in_review`, prompt reviewer to open the ACN tab |
+| ACN → Paperclip | `task.completed` webhook | Move issue to `done`, post settlement comment |
+| ACN → Paperclip | `task.rejected` / `task.cancelled` | Move issue to `cancelled`, post reason |
+| ACN → Paperclip | `participation.rejected` | Post rejection reason + resubmit-count comment |
+| Paperclip → ACN | Issue **created** by a human (not by this plugin) | Create a corresponding ACN task in the configured subnet |
+| Paperclip → ACN | Issue moved to `done` (and `Auto-approve` enabled) | Call `/tasks/:id/review` → approve & settle |
+| Paperclip → ACN | Issue moved to `cancelled` | Call `/tasks/:id/review` → reject |
+| UI | ACN tab on issue | Show task ID, status, reward, participants; approve / reject pending submission |
+
+> **Note (v0.1):** the plugin does **not** create or sync Paperclip agents from ACN. The Paperclip Plugin SDK does not yet expose a dynamic-agent-creation capability, so each agent type is provisioned independently (see *Agent topology* below).
+
+## Architecture
+
+```
+Paperclip (L2 Orchestration: issues, agents, runs)
+  ↕ plugin (this repo)
+ACN (L1 Identity + Routing + L3 Settlement)
+```
+
+The plugin runs inside Paperclip's plugin worker sandbox. It uses the official
+[`acn-client`](https://www.npmjs.com/package/acn-client) TypeScript SDK to call
+ACN's REST API, and consumes ACN's per-subnet **Org Harness** webhook to
+receive task lifecycle events.
+
+### Agent topology
+
+| Agent type | Lives in Paperclip? | Lives in ACN? | How tasks reach it |
+|---|---|---|---|
+| **Paperclip native** | yes | optional | Paperclip wakeup; if registered in ACN it can also receive ACN tasks via its ACN endpoint |
+| **ACN-only solver** | no | yes | ACN A2A messaging / task pool; this plugin surfaces the task in Paperclip for human review only |
+| **External ACN agent** | no | yes (different org) | ACN inter-subnet messaging |
+
+## Installation
+
+### Prerequisites
+
+- A running Paperclip instance (self-hosted, with the plugin worker enabled)
+- An ACN deployment you can reach from the Paperclip host
+- An ACN **agent API key** (`acn_…`) with `task.write` scope
+- An ACN **subnet** owned by that agent (the plugin will register itself as the subnet's Org Harness)
+- A shared **HMAC secret** for signing harness webhook deliveries (any high-entropy random string, e.g. `openssl rand -hex 32`)
+
+### 1. Install into Paperclip
+
+```bash
+paperclipai plugin install @acnlabs/paperclip-plugin-acn
+```
+
+This pulls the latest release from npm and registers it with the local Paperclip instance. Alternatively, for a working-copy install (useful while developing the plugin itself):
+
+```bash
+git clone https://github.com/acnlabs/paperclip-acn-plugin.git
+cd paperclip-acn-plugin
+npm install
+npm run build         # produces dist/manifest.js, dist/worker.js, dist/ui/index.js
+paperclipai plugin install ./
+```
+
+### 2. Configure the plugin
+
+Paperclip → **Instance Settings → Plugins → ACN**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `acnBaseUrl` | yes | Base URL of the ACN instance (no trailing slash), e.g. `https://acn.agentplanet.io` |
+| `paperclipBaseUrl` | **strongly recommended** | Publicly reachable base URL of **this** Paperclip instance (e.g. `https://app.paperclip.ai`). Used to construct the harness webhook URL ACN posts to. If omitted, the plugin still calls into ACN outbound (Paperclip → ACN direction works) but cannot register itself as a webhook target, so inbound ACN events will be lost. |
+| `acnApiKeyRef` | yes | Secret reference to the ACN agent API key (`acn_…`). Resolved at runtime via Paperclip's secret provider. |
+| `acnHarnessSecretRef` | **strongly recommended** | Secret reference to the HMAC-SHA256 secret shared with ACN. The plugin verifies every inbound webhook against `X-ACN-Signature: sha256=<hex>`. **Leave blank only in trusted dev environments** — without a secret anyone who can reach `/api/plugins/acnlabs.acn/webhooks/acn-events` can forge ACN events. |
+| `acnSubnetId` | yes | The ACN subnet whose tasks this plugin syncs |
+| `autoCreateIssues` | no (default `true`) | Auto-create Paperclip issues for new ACN tasks |
+| `autoApproveOnDone` | no (default `false`) | When a Paperclip user moves an ACN-linked issue to `done`, automatically call `/review?approved=true` and release payment. Off by default — keeps a human in the loop. |
+
+### 3. Verify
+
+On worker startup the plugin:
+
+1. Resolves the API key and harness secret
+2. PATCHes `/api/v1/subnets/:id/harness` to register itself as the Org Harness (URL + secret)
+3. Does a full pull of `status in (open, in_progress, submitted)` ACN tasks for the subnet and mirrors them as Paperclip issues
+4. Subscribes to `issue.created` / `issue.updated` events
+
+Successful boot logs (visible in **Instance Settings → Plugins → ACN → Logs**):
+
+```
+acn-plugin: registered harness { subnet_id: "...", webhook_url: "...", signed: true }
+acn-plugin: setup complete { subnet_id: "..." }
+```
+
+If `signed: false` appears, the HMAC secret was **not** configured — the plugin will accept unsigned webhooks. Fix `acnHarnessSecretRef` in production.
+
+## Usage
+
+### ACN task → Paperclip issue
+
+When a task is created in the configured subnet, ACN posts `task.created` to the harness URL. The plugin verifies the HMAC signature, fetches full task details, then creates a Paperclip issue:
+
+| ACN event | Paperclip issue status |
+|---|---|
+| `task.created` | `todo` |
+| `task.accepted` | `in_progress` |
+| `task.submitted` | `in_review` |
+| `task.completed` | `done` |
+| `task.rejected` / `task.cancelled` | `cancelled` |
+
+Each transition is annotated with a comment summarising the event (assignee, settlement note, rejection reason, …).
+
+### Paperclip issue → ACN task
+
+When a Paperclip user creates an issue **that did not originate from this plugin** (detected via `event.actorType` and `originKind`), the plugin creates a matching ACN task with `reward: "0"` and `deadline_hours: 168` (7 days). Tune these defaults by extending `handleIssueCreated()` in `src/worker.ts`.
+
+### Manual review (ACN tab)
+
+Open any ACN-linked issue and click the **ACN** tab to:
+
+- See the linked ACN task ID, status, and reward
+- View each participant's submission content (fetched live from ACN)
+- Approve or reject the pending submission with optional notes
+
+Approve and Reject both call `POST /api/v1/tasks/:id/review` with the appropriate `approved` flag and `notes` payload.
+
+## Security model
+
+- **Inbound**: every ACN webhook is verified with HMAC-SHA256 against `X-ACN-Signature: sha256=<hex>` using the configured secret. Signature mismatch → request dropped, request_id logged. The secret is resolved via `ctx.secrets.resolve()`, never embedded in config.
+- **Outbound**: ACN API calls use `Authorization: Bearer <acn_api_key>`. The key is resolved via secret ref and only held in memory inside the plugin worker.
+- **State scope**: the `taskId → issueId` map is stored under `scopeKind: "company"`, so each company has its own isolated mapping.
+- **Echo loops**: `handleIssueCreated` and `handleIssueUpdated` both skip events where `event.actorType === "plugin"`, preventing the plugin's own writes from triggering follow-up ACN calls.
+
+## Development
+
+```bash
+npm run dev        # tsc --watch (worker only)
+npm run build      # full build: tsc + esbuild UI bundle
+npm run typecheck  # tsc --noEmit
+```
+
+The plugin is runtime-typed against `@paperclipai/plugin-sdk` and `acn-client`, both pulled from npm. To work against a local SDK checkout, point the `acn-client` dependency at a sibling working tree (e.g. `npm install ../acn/clients/typescript`) — but remember to revert before releasing.
+
+### End-to-end smoke
+
+The `scripts/` folder ships three live integration probes against a running ACN + Paperclip pair:
+
+```bash
+node scripts/provision-e2e.mjs                # one-shot setup (bridge agent + subnet + secrets)
+node scripts/e2e-lifecycle.mjs                # PC issue ↔ ACN task full path todo → done
+node scripts/e2e-acn-to-paperclip.mjs         # external ACN task → PC mirror issue
+node scripts/e2e-paperclip-to-acn.mjs         # PC issue → ACN task + echo-loop guard
+```
+
+## License
+
+MIT — ACN Labs

package/dist/constants.d.ts

@@ -0,0 +1,17 @@
+export declare const PLUGIN_ID = "acnlabs.acn";
+export declare const PLUGIN_VERSION = "0.1.0";
+export declare const WEBHOOK_KEYS: {
+    readonly acnEvents: "acn-events";
+};
+export declare const SLOT_IDS: {
+    readonly issueTab: "acn-issue-tab";
+};
+export declare const EXPORT_NAMES: {
+    readonly issueTab: "ACNIssueTab";
+};
+/** Plugin state keys. State is company-scoped (see `loadMap`/`saveMap`). */
+export declare const STATE_KEYS: {
+    /** Map of ACN taskId → Paperclip issueId. */
+    readonly issueTaskMap: "issue-task-map";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,gBAAgB,CAAC;AACvC,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,eAAO,MAAM,YAAY;;CAEf,CAAC;AAEX,eAAO,MAAM,QAAQ;;CAEX,CAAC;AAEX,eAAO,MAAM,YAAY;;CAEf,CAAC;AAEX,4EAA4E;AAC5E,eAAO,MAAM,UAAU;IACrB,6CAA6C;;CAErC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,17 @@
+export const PLUGIN_ID = "acnlabs.acn";
+export const PLUGIN_VERSION = "0.1.0";
+export const WEBHOOK_KEYS = {
+    acnEvents: "acn-events",
+};
+export const SLOT_IDS = {
+    issueTab: "acn-issue-tab",
+};
+export const EXPORT_NAMES = {
+    issueTab: "ACNIssueTab",
+};
+/** Plugin state keys. State is company-scoped (see `loadMap`/`saveMap`). */
+export const STATE_KEYS = {
+    /** Map of ACN taskId → Paperclip issueId. */
+    issueTaskMap: "issue-task-map",
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS,EAAE,YAAY;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ,EAAE,eAAe;CACjB,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,aAAa;CACf,CAAC;AAEX,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,6CAA6C;IAC7C,YAAY,EAAE,gBAAgB;CACtB,CAAC"}

package/dist/lib/echo-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Echo-loop guards for Paperclip → ACN handlers.
+ *
+ * When this plugin creates or updates a Paperclip issue in response to an
+ * ACN webhook, the resulting `issue.created` / `issue.updated` event would
+ * normally fan back out to our own listeners and trigger a redundant call
+ * to ACN (e.g. creating a duplicate task). We need to drop those events
+ * without depending on `taskIssueMap`, which is updated *after* the write
+ * lands and is therefore racy.
+ *
+ * Two signals are checked, in order:
+ *
+ * 1. `event.actorType === "plugin"` — set by the Paperclip host before the
+ *    event is dispatched, so it is race-free.
+ * 2. `event.payload.originKind` starts with `plugin:<this-plugin-id>` —
+ *    catches the rare case where another part of the system replays a
+ *    plugin-authored event without preserving `actorType`.
+ */
+export interface MinimalPluginEvent {
+    actorType?: "user" | "agent" | "system" | "plugin";
+    payload?: unknown;
+}
+/**
+ * Returns `true` when the event should be skipped because it was authored
+ * by this plugin (or another plugin instance).
+ */
+export declare function shouldSkipPluginEcho(event: MinimalPluginEvent, pluginId: string): boolean;
+//# sourceMappingURL=echo-guard.d.ts.map

package/dist/lib/echo-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo-guard.d.ts","sourceRoot":"","sources":["../../src/lib/echo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,MAAM,GACf,OAAO,CAgBT"}

package/dist/lib/echo-guard.js

@@ -0,0 +1,40 @@
+/**
+ * Echo-loop guards for Paperclip → ACN handlers.
+ *
+ * When this plugin creates or updates a Paperclip issue in response to an
+ * ACN webhook, the resulting `issue.created` / `issue.updated` event would
+ * normally fan back out to our own listeners and trigger a redundant call
+ * to ACN (e.g. creating a duplicate task). We need to drop those events
+ * without depending on `taskIssueMap`, which is updated *after* the write
+ * lands and is therefore racy.
+ *
+ * Two signals are checked, in order:
+ *
+ * 1. `event.actorType === "plugin"` — set by the Paperclip host before the
+ *    event is dispatched, so it is race-free.
+ * 2. `event.payload.originKind` starts with `plugin:<this-plugin-id>` —
+ *    catches the rare case where another part of the system replays a
+ *    plugin-authored event without preserving `actorType`.
+ */
+/**
+ * Returns `true` when the event should be skipped because it was authored
+ * by this plugin (or another plugin instance).
+ */
+export function shouldSkipPluginEcho(event, pluginId) {
+    if (event.actorType === "plugin")
+        return true;
+    const payload = event.payload;
+    const originKind = payload?.originKind;
+    // Require the trailing `:` separator (or exact match) so that a plugin
+    // named `acnlabs.acn` does not also swallow events emitted by some other
+    // plugin called `acnlabs.acnplus`. Acceptable shapes:
+    //   plugin:<pluginId>
+    //   plugin:<pluginId>:<entity-kind>
+    if (originKind) {
+        const prefix = `plugin:${pluginId}`;
+        if (originKind === prefix || originKind.startsWith(`${prefix}:`))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=echo-guard.js.map

package/dist/lib/echo-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo-guard.js","sourceRoot":"","sources":["../../src/lib/echo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAyB,EACzB,QAAgB;IAEhB,IAAI,KAAK,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE9C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAqD,CAAC;IAC5E,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;IACvC,uEAAuE;IACvE,yEAAyE;IACzE,sDAAsD;IACtD,sBAAsB;IACtB,oCAAoC;IACpC,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,UAAU,QAAQ,EAAE,CAAC;QACpC,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IAChF,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/secrets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve a plugin config field that may hold either:
+ *   1. A UUID-shaped Paperclip secret reference (resolved via the host) — used
+ *      once Paperclip enables company-scoped plugin secret refs.
+ *   2. A literal value (e.g. an ACN agent api_key or a hex-encoded HMAC secret)
+ *      — used today, because the current Paperclip build hard-disables secret
+ *      refs in plugin config (`PLUGIN_SECRET_REFS_DISABLED_MESSAGE`).
+ *
+ * This dual mode lets operators move forward without waiting for the upstream
+ * "company-scoped plugin config" milestone and keeps the same code path live
+ * once that lands — only the config value format flips.
+ *
+ * Decision is made purely on the **shape** of the ref string, never on
+ * runtime errors, so a typo never silently leaks plaintext to the worker.
+ */
+export declare function looksLikeSecretRef(value: string): boolean;
+export interface SecretsResolver {
+    resolve(ref: string): Promise<string>;
+}
+/**
+ * @param ref      The config value (UUID secret ref OR literal).
+ * @param secrets  The plugin host's secrets adapter (`ctx.secrets`).
+ *
+ * If `ref` is UUID-shaped, asks the host to resolve it.
+ * Otherwise returns it verbatim.
+ */
+export declare function resolveSecretOrLiteral(ref: string, secrets: SecretsResolver): Promise<string>;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/lib/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/lib/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/lib/secrets.js

@@ -0,0 +1,33 @@
+/**
+ * Resolve a plugin config field that may hold either:
+ *   1. A UUID-shaped Paperclip secret reference (resolved via the host) — used
+ *      once Paperclip enables company-scoped plugin secret refs.
+ *   2. A literal value (e.g. an ACN agent api_key or a hex-encoded HMAC secret)
+ *      — used today, because the current Paperclip build hard-disables secret
+ *      refs in plugin config (`PLUGIN_SECRET_REFS_DISABLED_MESSAGE`).
+ *
+ * This dual mode lets operators move forward without waiting for the upstream
+ * "company-scoped plugin config" milestone and keeps the same code path live
+ * once that lands — only the config value format flips.
+ *
+ * Decision is made purely on the **shape** of the ref string, never on
+ * runtime errors, so a typo never silently leaks plaintext to the worker.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function looksLikeSecretRef(value) {
+    return UUID_RE.test(value);
+}
+/**
+ * @param ref      The config value (UUID secret ref OR literal).
+ * @param secrets  The plugin host's secrets adapter (`ctx.secrets`).
+ *
+ * If `ref` is UUID-shaped, asks the host to resolve it.
+ * Otherwise returns it verbatim.
+ */
+export async function resolveSecretOrLiteral(ref, secrets) {
+    if (looksLikeSecretRef(ref)) {
+        return secrets.resolve(ref);
+    }
+    return ref;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/lib/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../src/lib/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,OAAO,GACX,iEAAiE,CAAC;AAEpE,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAMD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAW,EACX,OAAwB;IAExB,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/signature.d.ts

@@ -0,0 +1,26 @@
+/**
+ * HMAC-SHA256 signature verification for inbound ACN harness webhooks.
+ *
+ * ACN signs every harness webhook delivery with
+ * `hmac_sha256(secret, raw_json_body).hexdigest()` and sends it in the
+ * `X-ACN-Signature: sha256=<hex>` request header (see
+ * `acn/protocols/ap2/webhook.py::_sign_payload`). The plugin worker is
+ * solely responsible for verifying this signature — the Paperclip host
+ * does not inspect plugin webhook bodies.
+ */
+/**
+ * Verify the `X-ACN-Signature` header against `rawBody` using the shared
+ * harness secret. Behaviour:
+ *
+ * - `secret === null` → returns `true` (no secret configured; operator has
+ *   already been warned at setup time). Use this mode only in trusted dev
+ *   environments.
+ * - header missing / malformed → returns `false`.
+ * - signature does not match → returns `false`.
+ * - signature matches → returns `true`.
+ *
+ * Constant-time comparison via {@link timingSafeEqual} prevents byte-by-byte
+ * timing oracles.
+ */
+export declare function verifyAcnSignature(headers: Record<string, string | string[]>, rawBody: string, secret: string | null): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/lib/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/lib/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC1C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAkBT"}

package/dist/lib/signature.js

@@ -0,0 +1,45 @@
+/**
+ * HMAC-SHA256 signature verification for inbound ACN harness webhooks.
+ *
+ * ACN signs every harness webhook delivery with
+ * `hmac_sha256(secret, raw_json_body).hexdigest()` and sends it in the
+ * `X-ACN-Signature: sha256=<hex>` request header (see
+ * `acn/protocols/ap2/webhook.py::_sign_payload`). The plugin worker is
+ * solely responsible for verifying this signature — the Paperclip host
+ * does not inspect plugin webhook bodies.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Verify the `X-ACN-Signature` header against `rawBody` using the shared
+ * harness secret. Behaviour:
+ *
+ * - `secret === null` → returns `true` (no secret configured; operator has
+ *   already been warned at setup time). Use this mode only in trusted dev
+ *   environments.
+ * - header missing / malformed → returns `false`.
+ * - signature does not match → returns `false`.
+ * - signature matches → returns `true`.
+ *
+ * Constant-time comparison via {@link timingSafeEqual} prevents byte-by-byte
+ * timing oracles.
+ */
+export function verifyAcnSignature(headers, rawBody, secret) {
+    if (!secret)
+        return true;
+    const headerKey = Object.keys(headers).find((k) => k.toLowerCase() === "x-acn-signature");
+    const raw = headerKey ? headers[headerKey] : undefined;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (!value)
+        return false;
+    const expected = createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
+    const got = value.startsWith("sha256=") ? value.slice(7) : value;
+    if (got.length !== expected.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(got, "hex"), Buffer.from(expected, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=signature.js.map

package/dist/lib/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/lib/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA0C,EAC1C,OAAe,EACf,MAAqB;IAErB,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,iBAAiB,CAC7C,CAAC;IACF,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpF,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACjE,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,4 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+declare const manifest: PaperclipPluginManifestV1;
+export default manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AASzE,QAAA,MAAM,QAAQ,EAAE,yBAyGf,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,97 @@
+import { EXPORT_NAMES, PLUGIN_ID, PLUGIN_VERSION, SLOT_IDS, WEBHOOK_KEYS, } from "./constants.js";
+const manifest = {
+    id: PLUGIN_ID,
+    apiVersion: 1,
+    version: PLUGIN_VERSION,
+    displayName: "ACN — Agent Collaboration Network",
+    description: "Connect Paperclip to ACN: sync tasks, manage agent identity, and settle work through the ACN protocol layer.",
+    author: "acnlabs",
+    categories: ["connector", "automation"],
+    entrypoints: {
+        worker: "dist/worker.js",
+        ui: "dist/ui",
+    },
+    capabilities: [
+        "companies.read",
+        "issues.read",
+        "issues.create",
+        "issues.update",
+        "issue.comments.read",
+        "issue.comments.create",
+        "agents.read",
+        "events.subscribe",
+        "webhooks.receive",
+        "http.outbound",
+        "secrets.read-ref",
+        "plugin.state.read",
+        "plugin.state.write",
+        "ui.detailTab.register",
+        "instance.settings.register",
+    ],
+    instanceConfigSchema: {
+        type: "object",
+        properties: {
+            acnBaseUrl: {
+                type: "string",
+                title: "ACN Base URL",
+                default: "https://acn.agentplanet.io",
+                description: "Base URL of the ACN instance (no trailing slash).",
+            },
+            paperclipBaseUrl: {
+                type: "string",
+                title: "Paperclip Base URL",
+                default: "",
+                description: "Public base URL of this Paperclip instance (e.g. https://app.paperclip.ai). Used to construct the ACN harness webhook URL.",
+            },
+            acnApiKeyRef: {
+                type: "string",
+                title: "ACN API Key (secret ref)",
+                default: "",
+                description: "Secret reference to the ACN agent API key used to call ACN on behalf of Paperclip.",
+            },
+            acnHarnessSecretRef: {
+                type: "string",
+                title: "ACN Harness Webhook Secret (secret ref)",
+                default: "",
+                description: "Secret reference to the shared HMAC-SHA256 secret used to sign and verify ACN harness webhook deliveries (X-ACN-Signature). Leave blank to skip verification (NOT recommended in production).",
+            },
+            acnSubnetId: {
+                type: "string",
+                title: "ACN Subnet ID",
+                default: "",
+                description: "The ACN subnet whose tasks this plugin syncs into Paperclip issues.",
+            },
+            autoCreateIssues: {
+                type: "boolean",
+                title: "Auto-create Paperclip issues for new ACN tasks",
+                default: true,
+            },
+            autoApproveOnDone: {
+                type: "boolean",
+                title: "Auto-approve ACN task when Paperclip issue moves to 'done'",
+                default: false,
+                description: "When disabled, a board member must click Approve in the ACN tab to release payment.",
+            },
+        },
+    },
+    webhooks: [
+        {
+            endpointKey: WEBHOOK_KEYS.acnEvents,
+            displayName: "ACN Task Events",
+            description: "Receives HMAC-signed lifecycle events from ACN (task.created, task.submitted, task.completed, ...).",
+        },
+    ],
+    ui: {
+        slots: [
+            {
+                type: "detailTab",
+                id: SLOT_IDS.issueTab,
+                displayName: "ACN",
+                exportName: EXPORT_NAMES.issueTab,
+                entityTypes: ["issue"],
+            },
+        ],
+    },
+};
+export default manifest;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,MAAM,QAAQ,GAA8B;IAC1C,EAAE,EAAE,SAAS;IACb,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,cAAc;IACvB,WAAW,EAAE,mCAAmC;IAChD,WAAW,EACT,8GAA8G;IAChH,MAAM,EAAE,SAAS;IACjB,UAAU,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IAEvC,WAAW,EAAE;QACX,MAAM,EAAE,gBAAgB;QACxB,EAAE,EAAE,SAAS;KACd;IAED,YAAY,EAAE;QACZ,gBAAgB;QAChB,aAAa;QACb,eAAe;QACf,eAAe;QACf,qBAAqB;QACrB,uBAAuB;QACvB,aAAa;QACb,kBAAkB;QAClB,kBAAkB;QAClB,eAAe;QACf,kBAAkB;QAClB,mBAAmB;QACnB,oBAAoB;QACpB,uBAAuB;QACvB,4BAA4B;KAC7B;IAED,oBAAoB,EAAE;QACpB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,cAAc;gBACrB,OAAO,EAAE,4BAA4B;gBACrC,WAAW,EAAE,mDAAmD;aACjE;YACD,gBAAgB,EAAE;gBAChB,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,oBAAoB;gBAC3B,OAAO,EAAE,EAAE;gBACX,WAAW,EACT,4HAA4H;aAC/H;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,0BAA0B;gBACjC,OAAO,EAAE,EAAE;gBACX,WAAW,EACT,oFAAoF;aACvF;YACD,mBAAmB,EAAE;gBACnB,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,yCAAyC;gBAChD,OAAO,EAAE,EAAE;gBACX,WAAW,EACT,+LAA+L;aAClM;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,eAAe;gBACtB,OAAO,EAAE,EAAE;gBACX,WAAW,EACT,qEAAqE;aACxE;YACD,gBAAgB,EAAE;gBAChB,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,gDAAgD;gBACvD,OAAO,EAAE,IAAI;aACd;YACD,iBAAiB,EAAE;gBACjB,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,4DAA4D;gBACnE,OAAO,EAAE,KAAK;gBACd,WAAW,EACT,qFAAqF;aACxF;SACF;KACF;IAED,QAAQ,EAAE;QACR;YACE,WAAW,EAAE,YAAY,CAAC,SAAS;YACnC,WAAW,EAAE,iBAAiB;YAC9B,WAAW,EACT,qGAAqG;SACxG;KACF;IAED,EAAE,EAAE;QACF,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,WAAW;gBACjB,EAAE,EAAE,QAAQ,CAAC,QAAQ;gBACrB,WAAW,EAAE,KAAK;gBAClB,UAAU,EAAE,YAAY,CAAC,QAAQ;gBACjC,WAAW,EAAE,CAAC,OAAO,CAAC;aACvB;SACF;KACF;CACF,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/ui/index.d.ts

@@ -0,0 +1,19 @@
+import { type PluginDetailTabProps } from "@paperclipai/plugin-sdk/ui";
+export interface AcnTaskInfo {
+    task_id: string;
+    title: string;
+    status: string;
+    /** Decimal string from ACN backend (e.g. "10.00"). */
+    reward: string;
+    reward_currency: string;
+    participations: Array<{
+        participation_id: string;
+        agent_id: string;
+        status: string;
+        submission_content: string | null;
+        submitted_at: string | null;
+        resubmit_count: number;
+    }>;
+}
+export declare function ACNIssueTab({ context }: PluginDetailTabProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.tsx"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AAIpC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,KAAK,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAyPD,wBAAgB,WAAW,CAAC,EAAE,OAAO,EAAE,EAAE,oBAAoB,2CAuF5D"}