# Cortex Repo API — Gmail server handoff

Updated: 2026-10-17. Cortex-side implementation is present; integration with the
other server and final Gmail-received headers have not been tested end to end.
Repo API starts disabled. No campaign or production connection key was selected
or enabled during development. Earlier suggested `/api/integrations/gmail/...`
paths were proposals; use the implemented paths below instead.

## Intended ownership and workflow

1. A Cortex administrator opens **Application Settings → Repo API**, enters a
   saved campaign ID, enables Repo API and saves. The server validates the
   campaign's configuration/resources. Saving generates a private connection
   key if none exists; **Copy key** copies it for backend configuration.
2. The Gmail API server authenticates the worker using its existing Google
   OAuth flow and obtains the Gmail address from Google. It authorizes the
   worker assignment and reads Cortex settings through the authenticated API.
3. That server creates an assignment task in Cortex. It cannot choose a
   campaign in the request: Cortex selects the admin-configured campaign.
4. Cortex queues one isolated send per distinct selected PowerMTA IP, preserving
   saved message content, placeholder replacement and header/body rotation.
   Each attempt gets a fixed RFC Message-ID. **No Repo tracking div is added.**
5. The Gmail server matches actual received messages using the manifest IDs,
   monitors their labels and displays its own progress/completion screens.
6. On completion, show the worker's connected Gmail address with “Submit this
   Gmail address as your proof.” The Gmail server owns completion evidence,
   later activity history, admin review/approval and recorded payment status.
   Cortex sending completion is not worker completion or payment approval.

Google tokens stay on the Gmail server. The private Cortex connection key
stays in that server's backend configuration; never expose it to browsers,
worker pages, URLs or logs. Google authorization alone is not authorization
for an external platform job. Assignment eligibility is the Gmail server's
responsibility. One trusted integration client is supported by this initial
implementation; it is not a multi-tenant campaign-selection API.

## Endpoints

Base URL: the Cortex master application's HTTPS origin, for example
`https://app.moreisheats.com`. Call these server to server, not through a page
server's port-8443 relay. All three routes require authentication.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/api/repo-api/settings` | Enabled state, selected campaign, revision, current expected count |
| POST | `/api/repo-api/tasks` | Prepare/queue a task, or recover the same request |
| GET | `/api/repo-api/tasks/{task_id}` | Read its immutable message manifest and sending states |

No query strings are accepted. Send `Accept: application/json`.
POST requires `Content-Type: application/json`. The API has a dedicated limit
of 600 requests/minute per source IP; respect `429` / `Retry-After` and cache
settings briefly. It does not share the ordinary API's 60/minute budget.

Disabling stops new assignments. Tasks already accepted, including recovery
of their queueing, continue using their saved plan. Existing task status stays
available. Changing the enabled flag or selected campaign changes the settings
revision; it does not change the connection key or old task manifests.

## Authentication — exact signing contract

The connection key displayed to the admin is a 64-character hexadecimal string.
Use its **ASCII text bytes as the HMAC secret**; do not hex-decode it.

Headers on every HTTP attempt:

- `X-Repo-Timestamp`: current Unix timestamp in seconds, 10 decimal digits.
- `X-Repo-Nonce`: a fresh random 16-byte value encoded as 32 lowercase hex digits.
- `X-Repo-Signature`: lowercase hex HMAC-SHA256 of the signing text below.
- `Idempotency-Key`: required on POST; omitted on GET.

Signing text, joined with literal LF (`\n`), with no extra trailing newline:

```text
UPPERCASE_HTTP_METHOD
EXACT_PATH_STARTING_WITH_/api/
TIMESTAMP_HEADER
NONCE_HEADER
IDEMPOTENCY_KEY_OR_EMPTY_STRING
LOWERCASE_SHA256_HEX_OF_EXACT_HTTP_BODY_BYTES
```

GET has an empty body and an empty idempotency-key line. Timestamps must be
within 300 seconds of Cortex time. Used nonces are rejected for 600 seconds.
**Every retry uses a new nonce/timestamp/signature while retaining the same
POST body, assignment ID and idempotency key.** Synchronize server clocks.

Python reference for producing headers (does not send a request):

```python
import hashlib, hmac, secrets, time

def signed_headers(secret, method, path, body=b"", idempotency_key=""):
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    text = "\n".join([
        method.upper(), path, timestamp, nonce, idempotency_key,
        hashlib.sha256(body).hexdigest(),
    ])
    headers = {
        "Accept": "application/json",
        "X-Repo-Timestamp": timestamp,
        "X-Repo-Nonce": nonce,
        "X-Repo-Signature": hmac.new(
            secret.encode("ascii"), text.encode("utf-8"), hashlib.sha256
        ).hexdigest(),
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
        headers["Content-Type"] = "application/json"
    return headers
```

Encode JSON once, sign those bytes, and send those same bytes. Signing one JSON
serialization and letting an HTTP library serialize it again can invalidate
the signature. Production keys are deliberately absent from this document.

## Settings response and task input

GET settings returns `success: true` and a `settings` object containing:

| Field | Meaning |
| --- | --- |
| `enabled` | Whether new tasks are accepted |
| `campaign_id` | Administrator's selected saved campaign, or null |
| `revision` | Opaque 32-character revision; copy it into new task requests |
| `expected_messages` | Current resolved IP count when enabled; zero when disabled |

If the selected campaign becomes unusable, settings returns 503
`CAMPAIGN_UNAVAILABLE`. Do not interpret this as worker failure.

POST body contains exactly the following required business fields:

| Field | Constraint |
| --- | --- |
| `assignment_id` | Stable backend-generated assignment identifier, 1–128 characters; letters/digits plus `.`, `_`, `:`, `-`; starts with letter/digit |
| `email` | Gmail address obtained from Google OAuth; canonicalized for dots, plus tags, case and googlemail aliases |
| `settings_revision` | Revision obtained from GET settings |

`Idempotency-Key` is 16–128 characters with the same character set as an
assignment ID. Persist it before making the first request. `campaign_id` in the
POST body is prohibited. Other worker-controlled routing/header/body options
are not accepted by the sending service.

Use globally distinct assignment IDs, including the platform/job/worker/run
identity as appropriate. A given assignment cannot switch its Gmail address
or settings revision later. Retrying an accepted task after a configuration
change must use its original body/revision. Do not generate a new assignment
or new idempotency key automatically to work around a conflict.

Response: `success`, `replayed`, and `task`. HTTP 202 means newly queued;
HTTP 200 means an existing assignment/request was returned. A non-whitelisted
mailbox already present in the campaign's linked email list produces HTTP 409,
`EMAIL_ALREADY_USED`, and a task with `sending_status: duplicate`. Current list
deduplication is list-wide, not just per external job. An address on the
administrator's existing test whitelist may repeat with separate assignments.

The task contains:

- `task_id`, `assignment_id`, canonical `email`, `campaign_id`,
  `settings_revision`, `created_at`.
- `expected_messages`: frozen for this task, regardless of later campaign edits.
- `sending_status`: `preparing`, `duplicate`, `queued`, `sending`, or `finished`.
- `send_counts`: counts by the per-message sending states below.
- `messages`: entries with `slot_id`, `attempt_id`, `message_id`, `send_state`,
  `finished_at` (null until a final result is stored).

The public response never includes sender payloads, connection credentials,
private keys, data-list contents or Google tokens. GET status is read-only.

## Message identity and truthful sending states

Each distinct selected IP has one logical `slot_id`, one current `attempt_id`,
and a literal RFC `Message-ID`, frozen before queueing. In this mode Cortex
replaces existing Message-ID lines in the run-local header variants with that
single ID. The saved campaign record is not edited. Its structure is:

```text
<repo-TASK_ID.SLOT_ID.ATTEMPT_ID@selected-sending-domain>
```

This is an RFC Message-ID, **not Gmail's own message resource ID** or the
internal numeric Cortex test UID. The Gmail server discovers Gmail's IDs after
arrival and maps them to the manifest. Match individual messages, not only
subjects or Gmail threads, and include Spam when discovering task mail.

| `send_state` | Meaning |
| --- | --- |
| `queued` | Awaiting a sending attempt |
| `submitting` | One worker owns the attempt |
| `smtp_accepted` | Exactly one explicit SMTP 250 result was reported by the immediate receiving SMTP service |
| `smtp_rejected` | One explicit SMTP 4xx/5xx rejection was reported |
| `unknown` | Timeout, crash, malformed/missing results or another uncertain outcome |
| `not_started` | Task rejected because the mailbox was already in its data list |

`smtp_accepted` does not mean delivered to Gmail. `finished` means sending
attempts have terminal outcomes, not that all messages arrived/read or that the
worker should be paid. Gmail observations remain necessary for those checks.
The current binary preserves supplied literal IDs in local SMTP captures,
including new API-generated headers, but PMTA-to-Gmail preservation still needs
an end-to-end test with an authorized test mailbox. Recheck on binary upgrades.

## Retry, recovery and pacing

Retry network failures and 503s with bounded exponential backoff and jitter,
honouring Retry-After. Retain the original POST body and idempotency key. If a
503 is returned during partial queueing, retry that POST; a GET alone does not
repair queue submission. Already queued slots keep their IDs and are skipped.

Both task plan and idempotency bindings are durable private files. Recipient
claims use a task-specific source tag so a crash after the SQL insert can
recover the same claim without duplicating or deleting recipient rows. A crash
after a queue insert but before its acknowledgement may leave duplicate queue
reservations; the locked per-slot sending claim allows only one SMTP attempt.

There are no automatic SMTP resends and no resend endpoint in this version.
An uncertain attempt stays unknown; do not recreate it with a fresh task ID.
No exactly-once delivery claim is made. A later explicit resend feature must
create a new attempt ID and Message-ID while retaining the logical slot.

Task messages use the existing four `repo-send` workers and wait at least three
seconds after the previous attempt for that task, across all its sending IPs.
Different tasks progress independently; queue load can increase delays. The
sender timeout is 60 seconds, worker timeout 75 and submission lease 90.

## Error handling

| HTTP / error | Client action |
| --- | --- |
| 401 `UNAUTHORIZED` | Check key, exact signing bytes/path, clock and headers |
| 401 `REPLAY_REJECTED` | Use a fresh nonce/signature; keep task identity/key |
| 409 `IDEMPOTENCY_CONFLICT` / `ASSIGNMENT_CONFLICT` | Investigate identity reuse; do not start another send automatically |
| 409 `SETTINGS_CHANGED` | Refresh settings; retry only if no task was accepted under the previous body |
| 409 `EMAIL_ALREADY_USED` | Show an already-used-mailbox outcome; no campaign is sent |
| 422 validation / `INVALID_EMAIL` / `IDEMPOTENCY_KEY_REQUIRED` | Correct input; no send was accepted for invalid input |
| 426 `HTTPS_REQUIRED` | Use HTTPS |
| 429 | Back off according to Retry-After |
| 503 `REPO_API_DISABLED` | Wait until enabled; do not keep creating assignments |
| 503 `PREPARATION_UNAVAILABLE` / `QUEUE_UNAVAILABLE` / `SERVICE_UNAVAILABLE` / `AUTH_STATE_UNAVAILABLE` | Retry the original request with fresh authentication |
| 404 `TASK_NOT_FOUND` | Verify the task ID; investigate missing state before sending again |

Gmail/API outages or revoked OAuth access must be distinct from worker
misconduct. A missing message in a partial Gmail query is not evidence of
deletion. Keep observed completion evidence separate from subsequent activity.

## Gmail server implementation scope

Reuse the design/CSS of `resources/views/repo_installer/worker-page.blade.php`
and `resources/repo/worker.css` / `favicon.svg`. Implement the Read messages and
completion screens in the API project's own framework. Existing `worker.js`
speaks the old signup/OTP/pixel/proof-code protocol and must not be copied as
the new API client unchanged. Keep the current Cortex signup pages working.

The Gmail server must freeze its own completion policy: required Inbox/read/
Starred/Important states, approved missing-delivery margin, task deadline and
post-completion review/monitoring window. These rules are not implemented or
returned by this minimal Cortex sending API. Already-read, newly matched task
messages can satisfy a read-state check; the API cannot prove human reading or
individual button clicks. Count a logical slot once, even if duplicate mail or
a future resend is observed. Payment approval remains manual.

## Storage, operations and validation

- Private configuration: `storage/app/repo/api-settings/` (encrypted key).
- Private tasks/requests/locks: `storage/app/repo/api/` (JSON records mode 0600).
- Back up settings, tasks and request bindings together. Do not apply the
  installer “latest 10” cleanup to these directories. Losing them can lose
  duplicate-request protection; investigate before retrying after a restore.
- Configuration is disabled by default; the admin must select/enable it.
- No migrations or dependency installations were needed. The existing database
  queue and separated recipient list are used. This API does not install pages
  on delivery servers, alter their routing or send verification-code emails.
- Backend code: `RepoApiSettings`, `RepoApiTaskService`, `RepoApiStore`,
  `RepoApiCampaignSender`, `RepoApiAuthentication`, `RepoApiController`,
  `RepoApiSendMessageJob`. Shared campaign preparation/rotation is reused.

Development checks used temporary state, mocked recipient writes/queues, safe
HTTP-kernel tests and a loopback SMTP receiver. Real campaign plans 10029 and
9841 were inspected read-only. No external emails, production recipient edits
or production API tasks were created. Local captures of API-generated payloads
confirmed exact manifest Message-IDs, valid MIME and no injected Repo div.

## Prompt for Codex on the Gmail API server

```text
The Cortex-side Repo API is implemented. First read the latest
environment/repo/GMAIL-API-HANDOFF.md from /var/www/cortex on the Cortex master
server. That document owns the implemented API contract; earlier suggested
endpoint names were proposals. Use read-only access to inspect Cortex.

Implement the Gmail API project's side using its existing OAuth and account
storage. Read Cortex settings, use the configured campaign/revision, and create
one durable assignment/idempotency key before requesting a send. Follow the
exact HMAC signing and retry/recovery rules. Keep credentials server-side.
Use Cortex's frozen RFC Message-ID manifest for matching, not subjects alone.

Build the Read messages and completion pages using the InboxTasks visual
design, adapted to this project's framework. No email OTP, injected Repo div,
VCODE or PCODE is needed. The completion proof shown to the worker is their
connected Gmail address. Admin review and payment status belong to this project.

Inspect existing completion/review rules before choosing defaults. Identify any
missing margin, timeout or monitoring-window decisions rather than inventing
automatic payment rules. Handle Gmail outages/revoked access separately from
worker actions. Preserve recorded evidence and count each logical message once.

Do not edit Cortex, its production data, or the old Repo workflow. Obtain the
connection key through Cortex's admin settings and existing secure configuration
process; never ask for it in chat. Test with a user-authorized test mailbox and
verify Gmail-received Message-ID preservation before accepting real assignments.
```
