Credential-based connectors (IMAP)

​

Motivation / problem

​

Theory & background

interface SupportsCredentialForm
{
    /** @return list<array<string,mixed>>  CredentialField::toArray() shapes. */
    public function credentialFormSchema(): array;
}

​

Design

1. Split the payload by target. The secret is pulled out (never written to config_json); connection fields nest under config_json['connection']; everything else is a top-level config_json key. Fields hidden by an unmet showIf are skipped so they never pollute the row.
2. Upsert the single (tenant_id, connector_name) row PENDING (R30 — every query is tenant-scoped).
3. basic-auth → mint the connector’s single-use OAuth state via initiateOAuth(), then immediately replay it through handleOAuthCallback() with the secret (posted under its schema field name). The connector pings the server and, on success, vaults the secret → row flips ACTIVE. A ConnectorAuthException (bad login) leaves the row PENDING with error_json and surfaces as HTTP 422 — never a 200-with-empty-body (skill surface-failures-loudly).
4. xoauth2 → persist PENDING and return the provider authorize URL; the browser redirects and the unchanged oauth/callback route finishes the flow.

​

Data model / contract

GET  /api/admin/connectors
  → data[].auth_kind: 'oauth' | 'credential'
  → data[].credential_form_schema: CredentialField[] | null

POST /api/admin/connectors/{name}/configure          (can:manageConnectors)
  body: { <field name>: value, …, project_key? }     # secret included, never logged
  → 200 { data: { id, status, last_sync_at, error, redirect_to } }
       redirect_to: string|null   # non-null only for xoauth2
  → 422 { error }                  # basic-auth credential ping failed
  → 422 { message, errors }        # validation (dynamic, from the schema)

# v8.24 — connection settings (the folder picker)
GET   /api/admin/connectors/{id}/folders             (can:manageConnectors)
  → 200 { data: { folders: string[] } }   # live mailbox paths
  → 404                                     # cross-tenant / unknown / non-IMAP id
  → 503 { error }                           # mailbox unreachable (never an empty 200)

PATCH /api/admin/connectors/{id}                      (can:manageConnectors)
  body: { folders?: { include: string[] }, date_window_days?: int, … }
  → 200 { data: { …, folders: { include }, date_window_days } }

​

Microsoft 365 app-only (client credentials) — auth_mode: xoauth2_client_credentials

​

Decision rationale (ADR-style)

• Reuse initiateOAuth/handleOAuthCallback, invent no new connector method. The installation lifecycle is identical; only the secret source differs. A bespoke handleCredentials() method would fork every connector’s contract and the host’s flow for no behavioural gain. The basic-auth path simply replays the connector’s own single-use state synthetically.
• Schema lives in the connector, not the host (Option A). With connector-base v1.2 + connector-imap v1.2 on Packagist, the field schema is the connector’s responsibility — one source of truth, no host/package drift (skill docs-match-code). The earlier “host-side schema map” fallback (Option B) was dropped.
• target-driven routing, not field-name magic. Routing by an explicit per-field target (rather than guessing from names) is what keeps the host generic: a future connector with an api_token secret and a base_url connection field works with zero host changes.
• The secret never touches config_json. It is routed through handleOAuthCallback straight to the encrypted vault. config_json (which can surface host/username metadata) carries no credential, and the ConnectorInstallationResource omits it from the API entirely.

​

Worked example — activate an IMAP mailbox

1. composer require padosoft/askmydocs-connector-imap (auto-discovered).
2. As a super-admin, open /app/admin/connectors → the Email (IMAP) tile in Available sources carries the Add (+) button.
3. Click Add (+) → a modal renders from the schema. For app-password auth: host = imap.example.com, port = 993, encryption = SSL/TLS, username = you@example.com, password = <app password>.
4. Connect → the BE logs in (a real IMAP ping), vaults the password, and the account appears Active in the Connections list. Bad credentials → an inline error, no connection is created, nothing is vaulted.
5. For Gmail / Microsoft 365 choose OAuth2 in the form → the browser redirects to the provider and returns ACTIVE through the standard callback.

​

Connection settings — the folder picker (v8.24)

• Empty selection = sync ALL non-excluded folders (the connector default — Trash/Spam/Junk/[Gmail]/Spam/[Gmail]/Trash). This is the both-states (R43) default every fresh account ships with.
• A non-empty selection is a whitelist that BYPASSES those exclusions — the modal warns about this so an operator doesn’t silently start ingesting spam.
• A previously-saved folder that has since vanished from the server stays visible (checked, flagged “not found”) so a save never silently drops it.

​

Gotchas & operations

• can:manageConnectors (admin + super-admin) gates configure — and the folder picker — like every other connector route; it touches credential vaults. Widened from super-admin-only in v8.24 so an admin can run the picker. Regression-locked in the R32 authorization matrix.
• One installation = one mailbox. Multi-mailbox per installation is out of scope (a second installation row covers a second mailbox).
• Testing seam. The IMAP server is a backend TCP dependency, so Playwright can’t stub it; E2E runs with CONNECTOR_IMAP_FAKE_PING=true, an input-driven offline fake (host containing invalid/fail → login failure). Default-OFF — production always talks to the real server (skill on both-state flags, R43).
• The mechanism is generic. Any future credential connector implements SupportsCredentialForm; the same form, endpoint, validation and vaulting work unchanged — no host edit.