Write an external connector

A connector plugs an external service (Notion, Zapier, etc.) into an arka-deck project via the connectors-core module. It registers available actions, manages credentials/OAuth, and exposes an execution journal.

---

Difference with a classic addon

Aspect	Addon	Connector
Core coupling	Consumes core ports	Consumes ConnectorRegistry + for-connectors
UI surface	Dedicated view, chat panel, etc.	Configuration view + audit-log
Authentication	Local-only	OAuth or external token
Data	Local	External reference + cache

The notion-connect addon is the reference implementation to study.

---

Typical structure

addons/<connector>/
├── manifest.json
└── src/
    ├── index.ts              # register + re-exports
    ├── manifest.ts           # TS ConnectorManifest, re-exported by index
    ├── adapters/             # HTTP client, OAuth
    ├── actions/              # one action = one external operation
    └── use-cases/

---

Steps

1. Declare the ConnectorManifest in src/manifest.ts (slug, label, actions, OAuth scopes, etc.).
2. Implement actions: each defines its input/output schema and handler.
3. Handle authentication: in-memory OAuth state with short TTL, or encrypted static token.
4. Register with the ConnectorRegistry in the composition root.
5. Tests: individual actions (Zod schemas), OAuth flow (mock state), audit-log.

---

Security

• Secrets (tokens, credentials) encrypted via the SecretCipher port (AES-256-GCM, see ADR 0005).
• OAuth state is ephemeral (short TTL, single use).
• The connector never imports the whole target workspace: it stores only references and explicit executions.

---

Resources

• Existing reference: notion-connect
• Addon contract (shared foundations): contrat-addon
• Secrets policy: ADR 0005
• Anti-SSRF policy: ADR 0006

---

Documentation status

This page is a stub. The full tutorial (connector skeleton, Zod schemas, audit-log, error handling) will be written during lot P4 from the addons/notion-connect/ code.