@atomicmail/agent-skill 0.1.0

package/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: atomic-mail
+description: Read and write email through the Atomic Mail ESP from an AI agent. Handles the proof-of-work authentication and JMAP protocol so the agent only needs to think in JMAP method calls. Use when the user asks to register an Atomic Mail inbox, list mailboxes, fetch emails, send email, or otherwise programmatically interact with their Atomic Mail account.
+license: MIT
+compatibility: Requires Deno 2.0+ to run scripts directly, or Node 20+ / Bun 1.1+ via `npx @atomic-mail/agent-skill` after publishing. Needs network access to the configured Atomic Mail auth-service and api-service.
+metadata:
+  author: atomic-mail
+  version: "0.1.0"
+---
+
+# Atomic Mail
+
+Atomic Mail is an AI-agent-first email service provider (ESP) that exposes a
+programmable inbox over JMAP. It uses a custom proof-of-work (PoW) signup flow
+plus three short-lived JWTs (challenge -> session -> capability). This skill
+hides all of that behind two CLI scripts so the agent can focus on JMAP.
+
+## When to use this skill
+
+Use this skill when the user wants to:
+
+- Register a new Atomic Mail inbox (signup with a username).
+- Re-authenticate an existing Atomic Mail account using its API key.
+- Read, search, or modify email via JMAP (`Mailbox/get`, `Email/query`,
+  `Email/get`, `Email/set`, etc.).
+- Send email via JMAP (`EmailSubmission/set` with the
+  `urn:ietf:params:jmap:submission` capability).
+- Discover the JMAP session object (`/.well-known/jmap`) to find the `accountId`
+  before issuing other JMAP method calls.
+
+## Available scripts
+
+- **`scripts/signup.ts`** — One-time setup: performs PoW signup or login and
+  writes credentials to disk. Run once per agent session/inbox.
+- **`scripts/jmap_request.ts`** — Sends JMAP requests using the saved
+  credentials. Auto-rotates the session and capability JWTs as they expire.
+
+Both scripts are invokable three ways. Pick the one that matches the runtime the
+user has installed:
+
+```bash
+# Deno (preferred — runs source directly)
+deno run -A scripts/signup.ts ...
+deno run -A scripts/jmap_request.ts ...
+
+# Node (after the npm package is installed/published)
+npx -y @atomic-mail/agent-skill atomic-mail-signup ...
+npx -y @atomic-mail/agent-skill atomic-mail-jmap ...
+
+# Bun
+bunx -y @atomic-mail/agent-skill atomic-mail-signup ...
+bunx -y @atomic-mail/agent-skill atomic-mail-jmap ...
+```
+
+> The agent should always pass `--help` first if it is unsure of the exact flag
+> spelling. Both scripts print full usage to stdout and exit `0`.
+
+## Required configuration
+
+The auth and API base URLs come from the Atomic Mail deployment. Pass them as
+flags or set them in the environment:
+
+| Flag            | Env var                   | Description                                             |
+| --------------- | ------------------------- | ------------------------------------------------------- |
+| `--auth-url`    | `ATOMIC_MAIL_AUTH_URL`    | Base URL of `auth-service` (PoW + JWT minting).         |
+| `--api-url`     | `ATOMIC_MAIL_API_URL`     | Base URL of `api-service` (JMAP).                       |
+| `--scrypt-salt` | `ATOMIC_MAIL_SCRYPT_SALT` | Optional PoW salt override (defaults match `auth-service`). |
+
+If the user does not know the URLs, ask them — they are deployment-specific.
+
+## Workflow
+
+### 1. First-time signup (new account)
+
+```bash
+deno run -A scripts/signup.ts \
+  --auth-url   "$ATOMIC_MAIL_AUTH_URL" \
+  --api-url    "$ATOMIC_MAIL_API_URL" \
+  --username   "alice" \
+  --out-dir    "./.atomic-mail"
+```
+
+This writes three files into `--out-dir`:
+
+- `credentials.json` — `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }`. The
+  agent should store the `apiKey` securely; it is the long-lived secret.
+- `session.jwt` — 4-hour session token.
+- `capability.jwt` — 2-minute capability token used as the JMAP bearer.
+
+The script prints a JSON summary to stdout that includes `inboxId` and `apiKey`.
+Save these in the agent's persistent memory (or echo them back to the user) —
+they are the only durable identifiers.
+
+### 2. Re-authenticate (existing API key)
+
+If `credentials.json` already exists, this is normally not needed —
+`jmap_request.ts` will auto-renew session/capability tokens via the stored API
+key. Use `signup.ts --api-key` only if the user wants to start a fresh
+credentials directory from a known API key.
+
+```bash
+deno run -A scripts/signup.ts \
+  --auth-url    "$ATOMIC_MAIL_AUTH_URL" \
+  --api-url     "$ATOMIC_MAIL_API_URL" \
+  --api-key     "11111111-2222-3333-4444-555555555555" \
+  --out-dir     "./.atomic-mail"
+```
+
+### 3. Discover the JMAP session
+
+Run this **once** before any other JMAP call to learn the `accountId` and
+mailbox structure.
+
+```bash
+deno run -A scripts/jmap_request.ts \
+  --credentials-dir "./.atomic-mail" \
+  --session
+```
+
+The response JSON contains `primaryAccounts`, `accounts`, `capabilities`, etc.
+Extract the `accountId` for the user's primary mail account from
+`primaryAccounts["urn:ietf:params:jmap:mail"]`.
+
+### 4. Send a JMAP request (inline ops)
+
+```bash
+deno run -A scripts/jmap_request.ts \
+  --credentials-dir "./.atomic-mail" \
+  --ops '[["Mailbox/get", {"accountId": "ACCOUNT_ID"}, "m0"]]'
+```
+
+For multiple method calls or capabilities, pass a full envelope:
+
+```bash
+deno run -A scripts/jmap_request.ts \
+  --credentials-dir "./.atomic-mail" \
+  --ops '{
+    "using": ["urn:ietf:params:jmap:core","urn:ietf:params:jmap:mail"],
+    "methodCalls": [
+      ["Mailbox/get", {"accountId": "ACCOUNT_ID"}, "m0"],
+      ["Email/query", {"accountId": "ACCOUNT_ID", "limit": 10}, "q0"]
+    ]
+  }'
+```
+
+### 5. Send a JMAP request (preset file)
+
+For repeated tasks, save the JMAP body to a file and reuse it. The file may
+contain either a `methodCalls` array or a full `{ using, methodCalls }`
+envelope.
+
+```bash
+cat > fetch_last_100.json <<'EOF'
+[
+  ["Email/query", {
+    "accountId": "ACCOUNT_ID",
+    "limit": 100,
+    "sort": [{ "property": "receivedAt", "isAscending": false }]
+  }, "q0"],
+  ["Email/get", {
+    "accountId": "ACCOUNT_ID",
+    "#ids": { "resultOf": "q0", "name": "Email/query", "path": "/ids" },
+    "properties": ["id","threadId","subject","from","receivedAt","preview"]
+  }, "g0"]
+]
+EOF
+
+deno run -A scripts/jmap_request.ts \
+  --credentials-dir "./.atomic-mail" \
+  --ops-file fetch_last_100.json
+```
+
+The agent can build a small library of these preset files (`send_email.json`,
+`mark_read.json`, etc.) and reuse them across runs.
+
+### 6. Send email
+
+Send is a JMAP `EmailSubmission/set` plus an optional `Email/set` to upload the
+draft. Remember to add the submission capability to `using`:
+
+```bash
+deno run -A scripts/jmap_request.ts \
+  --credentials-dir "./.atomic-mail" \
+  --using "urn:ietf:params:jmap:core,urn:ietf:params:jmap:mail,urn:ietf:params:jmap:submission" \
+  --ops-file send_email.json
+```
+
+## Token rotation (handled automatically)
+
+`jmap_request.ts` checks both JWTs before every request:
+
+- If `capability.jwt` is within 20 s of expiry, it calls
+  `POST /api/v1/capability` with the existing session JWT and rewrites
+  `capability.jwt`.
+- If `session.jwt` is within 60 s of expiry (or missing), it re-runs the full
+  PoW handshake using the API key from `credentials.json`, then rewrites both
+  `session.jwt` and `capability.jwt`.
+
+The agent does not need to call `signup.ts` again to refresh tokens — it only
+needs to call `signup.ts` for the very first registration of an account.
+
+## Troubleshooting
+
+- **`Could not read credentials file ... Did you run signup first?`** — Run
+  `signup.ts` once with `--username` (new account) or `--api-key` (existing
+  account) to create the file set.
+- **`auth-service /api/v1/session returned 409`** — The challenge was consumed
+  (likely a duplicate request or a clock skew). Just rerun `signup.ts` or the
+  failing `jmap_request.ts` once; a fresh challenge will be issued.
+- **`auth-service /api/v1/session returned 401`** — The `apiKey` in
+  `credentials.json` is unknown or suspended. Re-register with `--username` or
+  get a new API key from the operator.
+- **PoW takes a long time on first run** — Difficulty is fixed at 6 leading zero
+  bits, which averages ~64 scrypt iterations. Each scrypt is ~16 MB and ~200-500
+  ms, so the whole solve typically completes in under 30 seconds on a modern
+  laptop.
+- **`Capability JWT did not contain an inboxId claim`** — Almost certainly a
+  server/version mismatch. Verify `--auth-url` points to a current
+  `auth-service` deployment.
+
+## Security notes
+
+- `credentials.json` contains the long-lived API key. The script writes it with
+  mode `0600`, but the agent must not echo the file's contents into shared logs
+  or commit it to source control.
+- Pick a credentials directory that is private to the agent's runtime user (e.g.
+  `~/.config/atomic-mail/` or a per-task working dir).
+- `session.jwt` and `capability.jwt` are short-lived but should be treated as
+  bearer credentials too — never log them.
+
+## Building an npm package
+
+Scripts can be published as an npm package so Node and Bun environments can use
+them through `npx` / `bunx`. From the skill directory:
+
+```bash
+deno task build:npm           # writes ./npm
+cd npm && npm publish --access public
+```
+
+After publishing, `npx @atomic-mail/agent-skill atomic-mail-signup` and
+`npx @atomic-mail/agent-skill atomic-mail-jmap` work without Deno installed.

package/esm/lib/src/consts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fixed proof-of-work scrypt salt. The auth-service passes this string (UTF-8
+ * bytes of the hex text, not decoded binary) to `scrypt` as the `salt`
+ * argument; all PoW clients must use the same value.
+ */
+export declare const DEFAULT_POW_SCRYPT_SALT_HEX = "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083";
+export declare const ONE_SEC_MS = 1000;
+export declare const ONE_MIN_MS: number;
+export declare const ONE_HOUR_MS: number;
+export declare const ONE_DAY_MS: number;
+export declare const ONE_MONTH_MS: number;
+export declare const ONE_YEAR_MS: number;
+//# sourceMappingURL=consts.d.ts.map

package/esm/lib/src/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../../src/lib/src/consts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,qEAC4B,CAAC;AAErE,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,eAAO,MAAM,UAAU,QAAkB,CAAC;AAC1C,eAAO,MAAM,WAAW,QAAkB,CAAC;AAC3C,eAAO,MAAM,UAAU,QAAmB,CAAC;AAC3C,eAAO,MAAM,YAAY,QAAkB,CAAC;AAC5C,eAAO,MAAM,WAAW,QAAmB,CAAC"}

package/esm/lib/src/consts.js

@@ -0,0 +1,12 @@
+/**
+ * Fixed proof-of-work scrypt salt. The auth-service passes this string (UTF-8
+ * bytes of the hex text, not decoded binary) to `scrypt` as the `salt`
+ * argument; all PoW clients must use the same value.
+ */
+export const DEFAULT_POW_SCRYPT_SALT_HEX = "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083";
+export const ONE_SEC_MS = 1000;
+export const ONE_MIN_MS = ONE_SEC_MS * 60;
+export const ONE_HOUR_MS = ONE_MIN_MS * 60;
+export const ONE_DAY_MS = ONE_HOUR_MS * 24;
+export const ONE_MONTH_MS = ONE_DAY_MS * 30;
+export const ONE_YEAR_MS = ONE_DAY_MS * 365;

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/skill/scripts/jmap_request.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=jmap_request.d.ts.map

package/esm/skill/scripts/jmap_request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jmap_request.d.ts","sourceRoot":"","sources":["../../../src/skill/scripts/jmap_request.ts"],"names":[],"mappings":""}

package/esm/skill/scripts/jmap_request.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// Atomic Mail skill: JMAP request.
+//
+// Sends a JMAP request to api-service using credentials previously written
+// by signup. Auto-rotates session JWT (re-running PoW) and capability JWT
+// when they are within their safety margin of expiry, and writes the rotated
+// tokens back to disk so subsequent invocations stay fresh.
+//
+// JMAP method calls can be supplied two ways:
+//   --ops '<json>'    inline JSON body
+//   --ops-file <path> read JSON body from a file (e.g. saved
+//                     "fetch_last_100.json" preset)
+//
+// In both cases, the JSON may be either:
+//   • an array of methodCalls, e.g. [["Mailbox/get", {...}, "m0"]]
+//   • a full envelope { using: [...], methodCalls: [...] }
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { readFile } from "node:fs/promises";
+import { CAPABILITY_SAFETY_MARGIN_MS, fetchCapability, isJwtExpired, performPoWAndSession, SESSION_SAFETY_MARGIN_MS, } from "./lib/auth.js";
+import { defaultFilesFromOutDir, readCredentials, tryReadJwtFile, writeJwtFile, } from "./lib/credentials.js";
+const DEFAULT_USING = [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+];
+const HELP = `Usage: atomic-mail-jmap [OPTIONS]
+
+Send a JMAP request to your Atomic Mail inbox using credentials previously
+written by atomic-mail-signup. Capability and session JWTs are renewed
+automatically when expired.
+
+Token sources (defaults are based on --credentials-dir):
+  --credentials-dir DIR     Directory containing credentials.json,
+                            session.jwt, capability.jwt. Default: cwd.
+  --credentials-file PATH   Override path to credentials.json.
+  --session-file PATH       Override path to session.jwt.
+  --capability-file PATH    Override path to capability.jwt.
+
+Request body (one of these is required):
+  --ops JSON                Inline JSON: either an array of methodCalls or
+                            a full { using, methodCalls } object.
+  --ops-file PATH           Read --ops content from a file. Useful for
+                            saving reusable presets like 'fetch_last_100.json'.
+  --session                 Fetch JMAP session metadata via
+                            GET /.well-known/jmap (no body).
+
+Other:
+  --using LIST              Comma-separated capability URNs. Overrides
+                            defaults: ${DEFAULT_USING.join(",")}.
+                            Ignored if the JSON envelope already sets 'using'.
+  --dry-run                 Print the resolved request to stdout without
+                            sending it. Tokens are NOT rotated.
+  --help, -h                Show this help.
+
+Exit codes:
+  0  success — server response printed to stdout
+  1  network error or HTTP non-2xx response from api-service / auth-service
+  2  invalid CLI usage / malformed credentials or ops JSON
+
+Examples:
+  # Inline ops
+  atomic-mail-jmap --ops '[["Mailbox/get", {"accountId":"abc"}, "m0"]]'
+
+  # Reusable preset file
+  echo '[["Email/query",{"accountId":"abc","limit":100,"sort":[{"property":"receivedAt","isAscending":false}]},"q0"]]' \\
+    > fetch_last_100.json
+  atomic-mail-jmap --ops-file fetch_last_100.json
+
+  # Session discovery
+  atomic-mail-jmap --session
+`;
+function fail(message, code = 1) {
+    process.stderr.write(`Error: ${message}\n`);
+    if (code === 2)
+        process.stderr.write("\nRun with --help for usage.\n");
+    process.exit(code);
+}
+function readArgs() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                "credentials-dir": { type: "string" },
+                "credentials-file": { type: "string" },
+                "session-file": { type: "string" },
+                "capability-file": { type: "string" },
+                ops: { type: "string" },
+                "ops-file": { type: "string" },
+                using: { type: "string" },
+                session: { type: "boolean" },
+                "dry-run": { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        fail(err.message, 2);
+    }
+    if (parsed.values.help) {
+        process.stdout.write(HELP);
+        process.exit(0);
+    }
+    const dir = parsed.values["credentials-dir"] ?? ".";
+    const defaults = defaultFilesFromOutDir(dir);
+    const credentialsFile = parsed.values["credentials-file"] ??
+        defaults.credentialsFile;
+    const sessionFile = parsed.values["session-file"] ??
+        defaults.sessionFile;
+    const capabilityFile = parsed.values["capability-file"] ??
+        defaults.capabilityFile;
+    const ops = parsed.values.ops;
+    const opsFile = parsed.values["ops-file"];
+    const sessionMode = parsed.values.session === true;
+    if (sessionMode && (ops || opsFile)) {
+        fail("--session cannot be combined with --ops or --ops-file.", 2);
+    }
+    if (!sessionMode && !ops && !opsFile) {
+        fail("Provide one of --ops, --ops-file, or --session.", 2);
+    }
+    if (ops && opsFile) {
+        fail("--ops and --ops-file are mutually exclusive.", 2);
+    }
+    const usingFlag = parsed.values.using;
+    const using = usingFlag
+        ? usingFlag.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
+        : undefined;
+    return {
+        credentialsFile,
+        sessionFile,
+        capabilityFile,
+        ops,
+        opsFile,
+        using,
+        sessionMode,
+        dryRun: parsed.values["dry-run"] === true,
+    };
+}
+async function loadOps(args) {
+    if (args.sessionMode)
+        return undefined;
+    let raw;
+    if (args.ops !== undefined) {
+        raw = args.ops;
+    }
+    else if (args.opsFile) {
+        try {
+            raw = await readFile(args.opsFile, "utf-8");
+        }
+        catch (err) {
+            fail(`Could not read --ops-file '${args.opsFile}': ${err.message}`, 2);
+        }
+    }
+    else {
+        fail("Internal: ops not provided", 2);
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (err) {
+        fail(`Invalid JSON in JMAP ops: ${err.message}`, 2);
+    }
+    let using = args.using ?? DEFAULT_USING;
+    let methodCalls;
+    if (Array.isArray(value)) {
+        methodCalls = value;
+    }
+    else if (value !== null &&
+        typeof value === "object" &&
+        Array.isArray(value.methodCalls)) {
+        const obj = value;
+        methodCalls = obj.methodCalls;
+        // Inline `using` only takes precedence if user did not pass --using.
+        if (Array.isArray(obj.using) && !args.using) {
+            using = obj.using.filter((u) => typeof u === "string");
+        }
+    }
+    else {
+        fail('JMAP ops must be a methodCalls array, e.g. [["Mailbox/get",{...},"m0"]], ' +
+            "or an object with a 'methodCalls' array.", 2);
+    }
+    return { using, methodCalls };
+}
+async function ensureFreshTokens(args) {
+    const credentials = await readCredentials(args.credentialsFile);
+    let sessionJWT = await tryReadJwtFile(args.sessionFile);
+    let capabilityJWT = await tryReadJwtFile(args.capabilityFile);
+    const sessionExpired = !sessionJWT ||
+        isJwtExpired(sessionJWT, SESSION_SAFETY_MARGIN_MS);
+    if (sessionExpired) {
+        process.stderr.write("Session JWT missing or near expiry — re-running PoW.\n");
+        const result = await performPoWAndSession({
+            authUrl: credentials.authUrl,
+            scryptSalt: credentials.scryptSalt,
+            apiKey: credentials.apiKey,
+        });
+        sessionJWT = result.sessionJWT;
+        // After session rotation, the previous capability JWT is also no longer
+        // recognized by auth-service (challenge-status cache reset), so force
+        // a refresh below.
+        capabilityJWT = undefined;
+        await writeJwtFile(args.sessionFile, sessionJWT);
+    }
+    const capabilityExpired = !capabilityJWT ||
+        isJwtExpired(capabilityJWT, CAPABILITY_SAFETY_MARGIN_MS);
+    if (capabilityExpired) {
+        process.stderr.write("Capability JWT missing or near expiry — refreshing.\n");
+        capabilityJWT = await fetchCapability(credentials.authUrl, sessionJWT);
+        await writeJwtFile(args.capabilityFile, capabilityJWT);
+    }
+    return {
+        capabilityJWT: capabilityJWT,
+        sessionJWT: sessionJWT,
+        credentials,
+    };
+}
+async function main() {
+    const args = readArgs();
+    const envelope = await loadOps(args);
+    if (args.dryRun) {
+        const credentials = await readCredentials(args.credentialsFile);
+        const url = args.sessionMode
+            ? `${credentials.apiUrl}/.well-known/jmap`
+            : `${credentials.apiUrl}/jmap/`;
+        const dryRun = {
+            method: args.sessionMode ? "GET" : "POST",
+            url,
+            headers: { Authorization: "Bearer <capability-jwt>" },
+            body: envelope ?? null,
+        };
+        process.stdout.write(JSON.stringify(dryRun, null, 2) + "\n");
+        return;
+    }
+    const tokens = await ensureFreshTokens(args);
+    if (args.sessionMode) {
+        const res = await fetch(`${tokens.credentials.apiUrl}/.well-known/jmap`, {
+            headers: { Authorization: `Bearer ${tokens.capabilityJWT}` },
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            fail(`JMAP session fetch failed (HTTP ${res.status}): ${body}`);
+        }
+        process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+        return;
+    }
+    const res = await fetch(`${tokens.credentials.apiUrl}/jmap/`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${tokens.capabilityJWT}`,
+        },
+        body: JSON.stringify(envelope),
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        fail(`JMAP request failed (HTTP ${res.status}): ${body}`);
+    }
+    process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+}
+main().catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});

package/esm/skill/scripts/lib/auth.d.ts

@@ -0,0 +1,42 @@
+export declare const SESSION_TTL_MS: number;
+export declare const CAPABILITY_TTL_MS: number;
+export declare const CAPABILITY_SAFETY_MARGIN_MS = 20000;
+export declare const SESSION_SAFETY_MARGIN_MS = 60000;
+export interface JwtPayload {
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    [key: string]: unknown;
+}
+export declare function decodeJwtPayload<T = JwtPayload>(jwt: string): T;
+export declare function isJwtExpired(jwt: string, marginMs: number): boolean;
+export declare function solvePow(challenge: string, difficulty: number, salt: string, onProgress?: (nonce: bigint) => void): Promise<{
+    powHex: string;
+    nonce: string;
+}>;
+export declare function fetchChallenge(authUrl: string): Promise<{
+    challengeJWT: string;
+    challenge: string;
+    difficulty: number;
+}>;
+export interface SessionResponse {
+    sessionJWT: string;
+    apiKey?: string;
+}
+export declare function exchangeSession(authUrl: string, body: {
+    challengeJWT: string;
+    powHex: string;
+    nonce: string;
+    apiKey?: string;
+    username?: string;
+}): Promise<SessionResponse>;
+export declare function fetchCapability(authUrl: string, sessionJWT: string): Promise<string>;
+export interface PerformPoWInput {
+    authUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    username?: string;
+    onPowProgress?: (nonce: bigint) => void;
+}
+export declare function performPoWAndSession(input: PerformPoWInput): Promise<SessionResponse>;
+//# sourceMappingURL=auth.d.ts.map

package/esm/skill/scripts/lib/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../src/skill/scripts/lib/auth.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,cAAc,QAAqB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAgB,CAAC;AAI/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE;AAsCD,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5C;AAiCD,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CAS1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAKD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/esm/skill/scripts/lib/auth.js

@@ -0,0 +1,163 @@
+// PoW + auth-service client used by signup.ts and jmap_request.ts.
+//
+// Mirrors services/auth-service/src/crypto.ts and the protocol implemented
+// in services/mcp-server-local/src/auth-session.ts. Uses only `node:` imports
+// so the same source runs on Deno, Node, and Bun unchanged.
+import { scrypt } from "node:crypto";
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+const POW_HASH_BYTES = 64;
+export const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
+export const CAPABILITY_TTL_MS = 2 * 60 * 1000;
+// Refresh window: how close to expiry before we re-issue. The server enforces
+// strict expiry, so the client must rotate before the wire-side TTL elapses.
+export const CAPABILITY_SAFETY_MARGIN_MS = 20_000;
+export const SESSION_SAFETY_MARGIN_MS = 60_000;
+export function decodeJwtPayload(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2) {
+        throw new Error("Malformed JWT: expected at least 2 dot-separated segments.");
+    }
+    const payloadB64Url = parts[1];
+    const padLen = (4 - (payloadB64Url.length % 4)) % 4;
+    const base64 = payloadB64Url
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(payloadB64Url.length + padLen, "=");
+    return JSON.parse(atob(base64));
+}
+export function isJwtExpired(jwt, marginMs) {
+    try {
+        const { exp } = decodeJwtPayload(jwt);
+        if (typeof exp !== "number")
+            return true;
+        return Date.now() >= exp * 1000 - marginMs;
+    }
+    catch {
+        return true;
+    }
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+function hasLeadingZeroBits(hash, bits) {
+    if (bits > hash.length * 8)
+        return false;
+    const fullBytes = Math.floor(bits / 8);
+    const remainingBits = bits % 8;
+    for (let i = 0; i < fullBytes; i++) {
+        if (hash[i] !== 0)
+            return false;
+    }
+    if (remainingBits > 0) {
+        const mask = (0xff << (8 - remainingBits)) & 0xff;
+        if ((hash[fullBytes] & mask) !== 0)
+            return false;
+    }
+    return true;
+}
+// auth-service passes the SCRYPT_SALT_HEX string directly as the `salt`
+// argument to node:crypto's scrypt (i.e. the UTF-8 bytes of the hex string,
+// NOT the decoded hex bytes). We mirror that exactly so client and server
+// derive the same digest.
+function scryptHash(data, salt) {
+    const bytes = new TextEncoder().encode(data);
+    return new Promise((resolve, reject) => {
+        scrypt(bytes, salt, POW_HASH_BYTES, SCRYPT_PARAMS, (err, derived) => {
+            if (err)
+                return reject(err);
+            resolve(new Uint8Array(derived));
+        });
+    });
+}
+export async function solvePow(challenge, difficulty, salt, onProgress) {
+    let nonce = 0n;
+    while (true) {
+        const digest = await scryptHash(`${challenge}:${nonce}`, salt);
+        if (hasLeadingZeroBits(digest, difficulty)) {
+            return { powHex: bytesToHex(digest), nonce: nonce.toString() };
+        }
+        nonce++;
+        if (onProgress && nonce % 64n === 0n)
+            onProgress(nonce);
+    }
+}
+async function postJson(url, body, headers = {}) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...(body ? { "Content-Type": "application/json" } : {}),
+            ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const path = (() => {
+        try {
+            return new URL(url).pathname;
+        }
+        catch {
+            return url;
+        }
+    })();
+    if (!res.ok) {
+        throw new Error(`auth-service ${path} returned ${res.status}: ${text}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`auth-service ${path} returned non-JSON body: ${text}`);
+    }
+}
+export async function fetchChallenge(authUrl) {
+    const data = await postJson(`${authUrl}/api/v1/challenge`, undefined);
+    if (typeof data.challengeJWT !== "string") {
+        throw new Error("Challenge response missing challengeJWT.");
+    }
+    const payload = decodeJwtPayload(data.challengeJWT);
+    if (typeof payload.jti !== "string" ||
+        typeof payload.difficulty !== "number") {
+        throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
+    }
+    return {
+        challengeJWT: data.challengeJWT,
+        challenge: payload.jti,
+        difficulty: payload.difficulty,
+    };
+}
+export async function exchangeSession(authUrl, body) {
+    const data = await postJson(`${authUrl}/api/v1/session`, { ...body });
+    if (typeof data.sessionJWT !== "string") {
+        throw new Error("Session response missing sessionJWT.");
+    }
+    return {
+        sessionJWT: data.sessionJWT,
+        apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
+    };
+}
+export async function fetchCapability(authUrl, sessionJWT) {
+    const data = await postJson(`${authUrl}/api/v1/capability`, undefined, { Authorization: `Bearer ${sessionJWT}` });
+    if (typeof data.capabilityJWT !== "string") {
+        throw new Error("Capability response missing capabilityJWT.");
+    }
+    return data.capabilityJWT;
+}
+// One round trip of: /challenge -> solve PoW -> /session.
+// `apiKey` (login) and `username` (signup) are mutually exclusive; the caller
+// must enforce that before calling.
+export async function performPoWAndSession(input) {
+    const { authUrl, scryptSalt } = input;
+    const { challengeJWT, challenge, difficulty } = await fetchChallenge(authUrl);
+    const { powHex, nonce } = await solvePow(challenge, difficulty, scryptSalt, input.onPowProgress);
+    return exchangeSession(authUrl, {
+        challengeJWT,
+        powHex,
+        nonce,
+        apiKey: input.apiKey,
+        username: input.username,
+    });
+}

package/esm/skill/scripts/lib/credentials.d.ts

@@ -0,0 +1,18 @@
+export interface Credentials {
+    apiKey: string;
+    inboxId: string;
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+}
+export interface SkillFiles {
+    credentialsFile: string;
+    sessionFile: string;
+    capabilityFile: string;
+}
+export declare function defaultFilesFromOutDir(outDir: string): SkillFiles;
+export declare function writeCredentials(path: string, creds: Credentials): Promise<void>;
+export declare function readCredentials(path: string): Promise<Credentials>;
+export declare function writeJwtFile(path: string, jwt: string): Promise<void>;
+export declare function tryReadJwtFile(path: string): Promise<string | undefined>;
+//# sourceMappingURL=credentials.d.ts.map

package/esm/skill/scripts/lib/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../../src/skill/scripts/lib/credentials.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiCxE;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B"}

package/esm/skill/scripts/lib/credentials.js

@@ -0,0 +1,66 @@
+// Credential file I/O. Three files form a complete skill credential set:
+//   credentials.json  — long-lived: apiKey, inboxId, server URLs, PoW salt.
+//   session.jwt       — short-lived (~4h): rotates via /session + PoW.
+//   capability.jwt    — short-lived (~2min): rotates via /capability.
+//
+// Files are written with mode 0600 so other local users cannot read them.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export function defaultFilesFromOutDir(outDir) {
+    const base = resolve(outDir);
+    return {
+        credentialsFile: join(base, "credentials.json"),
+        sessionFile: join(base, "session.jwt"),
+        capabilityFile: join(base, "capability.jwt"),
+    };
+}
+async function ensureParent(path) {
+    await mkdir(dirname(path), { recursive: true });
+}
+export async function writeCredentials(path, creds) {
+    await ensureParent(path);
+    await writeFile(path, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+}
+export async function readCredentials(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Could not read credentials file '${path}': ${err.message}. ` +
+            "Did you run signup first?");
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Credentials file '${path}' is not valid JSON: ${err.message}`);
+    }
+    const required = [
+        "apiKey",
+        "inboxId",
+        "authUrl",
+        "apiUrl",
+        "scryptSalt",
+    ];
+    for (const k of required) {
+        if (typeof obj[k] !== "string" || obj[k].length === 0) {
+            throw new Error(`Credentials file '${path}' missing required field: ${k}`);
+        }
+    }
+    return obj;
+}
+export async function writeJwtFile(path, jwt) {
+    await ensureParent(path);
+    await writeFile(path, jwt, { mode: 0o600 });
+}
+export async function tryReadJwtFile(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        return raw.trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/esm/skill/scripts/signup.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=signup.d.ts.map

package/esm/skill/scripts/signup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signup.d.ts","sourceRoot":"","sources":["../../../src/skill/scripts/signup.ts"],"names":[],"mappings":""}

package/esm/skill/scripts/signup.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// Atomic Mail skill: signup / login.
+//
+// Performs the full PoW handshake against auth-service:
+//   POST /api/v1/challenge  -> { challengeJWT }
+//   solve scrypt PoW
+//   POST /api/v1/session    -> { sessionJWT, apiKey? }
+//   POST /api/v1/capability -> { capabilityJWT }
+//
+// Writes three files into --out-dir:
+//   credentials.json   stable account info + server config
+//   session.jwt        4h TTL, rotated by jmap_request when expired
+//   capability.jwt     2m TTL, rotated by jmap_request before each request
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../../lib/src/consts.js";
+import { decodeJwtPayload, fetchCapability, performPoWAndSession, } from "./lib/auth.js";
+import { defaultFilesFromOutDir, writeCredentials, writeJwtFile, } from "./lib/credentials.js";
+const HELP = `Usage: atomic-mail-signup [OPTIONS]
+
+Register a new Atomic Mail account, or log in with an existing API key.
+Persists credentials to disk so subsequent atomic-mail-jmap invocations
+work without re-authentication.
+
+Options:
+  --auth-url URL       Auth-service base URL.
+                       [env: ATOMIC_MAIL_AUTH_URL]
+  --api-url URL        API-service base URL (stored for jmap_request).
+                       [env: ATOMIC_MAIL_API_URL]
+  --scrypt-salt SALT   Override PoW scrypt salt (defaults to the deployment
+                       constant). [env: ATOMIC_MAIL_SCRYPT_SALT]
+  --username NAME      Register a NEW account with this username. The server
+                       returns a freshly minted API key. Mutually exclusive
+                       with --api-key.
+  --api-key KEY        Log in with an existing API key. Mutually exclusive
+                       with --username.
+  --out-dir DIR        Directory to write credential files into.
+                       Default: current working directory.
+  --quiet              Suppress progress messages on stderr.
+  --help, -h           Show this help.
+
+Output files (in --out-dir):
+  credentials.json   { apiKey, inboxId, authUrl, apiUrl, scryptSalt }
+  session.jwt        Session JWT (4h TTL).
+  capability.jwt     Capability JWT (2m TTL).
+
+Exit codes:
+  0  success
+  1  network error, server rejection, or unexpected response shape
+  2  invalid CLI usage (missing/conflicting flags)
+
+Examples:
+  atomic-mail-signup --auth-url https://auth.example.com \\
+                     --api-url  https://api.example.com  \\
+                     --username  alice
+  atomic-mail-signup --api-key 11111111-2222-3333-4444-555555555555
+`;
+function fail(message, code = 1) {
+    process.stderr.write(`Error: ${message}\n`);
+    if (code === 2)
+        process.stderr.write("\nRun with --help for usage.\n");
+    process.exit(code);
+}
+function readArgs() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                "auth-url": { type: "string" },
+                "api-url": { type: "string" },
+                "scrypt-salt": { type: "string" },
+                username: { type: "string" },
+                "api-key": { type: "string" },
+                "out-dir": { type: "string" },
+                quiet: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        fail(err.message, 2);
+    }
+    if (parsed.values.help) {
+        process.stdout.write(HELP);
+        process.exit(0);
+    }
+    const env = process.env;
+    const authUrl = parsed.values["auth-url"] ??
+        env.ATOMIC_MAIL_AUTH_URL ?? "";
+    const apiUrl = parsed.values["api-url"] ??
+        env.ATOMIC_MAIL_API_URL ?? "";
+    const scryptSalt = parsed.values["scrypt-salt"] ??
+        env.ATOMIC_MAIL_SCRYPT_SALT ?? DEFAULT_POW_SCRYPT_SALT_HEX;
+    const outDir = parsed.values["out-dir"] ?? ".";
+    if (!authUrl) {
+        fail("--auth-url is required (or set ATOMIC_MAIL_AUTH_URL).", 2);
+    }
+    if (!apiUrl) {
+        fail("--api-url is required (or set ATOMIC_MAIL_API_URL).", 2);
+    }
+    const username = parsed.values.username;
+    const apiKey = parsed.values["api-key"];
+    if (!!username === !!apiKey) {
+        fail("Provide exactly one of --username (new account) or --api-key (login).", 2);
+    }
+    return {
+        authUrl: authUrl.replace(/\/+$/, ""),
+        apiUrl: apiUrl.replace(/\/+$/, ""),
+        scryptSalt,
+        username,
+        apiKey,
+        outDir,
+        quiet: parsed.values.quiet === true,
+    };
+}
+async function main() {
+    const args = readArgs();
+    const files = defaultFilesFromOutDir(args.outDir);
+    const log = (msg) => {
+        if (!args.quiet)
+            process.stderr.write(msg + "\n");
+    };
+    log(args.username
+        ? `Registering new account "${args.username}"...`
+        : `Logging in with existing API key...`);
+    log(`Solving PoW + exchanging session against ${args.authUrl}...`);
+    const session = await performPoWAndSession({
+        authUrl: args.authUrl,
+        scryptSalt: args.scryptSalt,
+        username: args.username,
+        apiKey: args.apiKey,
+    });
+    const apiKey = session.apiKey ?? args.apiKey;
+    if (!apiKey) {
+        fail("Session response did not include an apiKey and none was provided. " +
+            "This indicates a server bug.");
+    }
+    log(`Fetching initial capability JWT...`);
+    const capabilityJWT = await fetchCapability(args.authUrl, session.sessionJWT);
+    const claims = decodeJwtPayload(capabilityJWT);
+    const inboxId = claims.inboxId;
+    if (typeof inboxId !== "string" || inboxId.length === 0) {
+        fail("Capability JWT did not contain an inboxId claim.");
+    }
+    await writeCredentials(files.credentialsFile, {
+        apiKey,
+        inboxId,
+        authUrl: args.authUrl,
+        apiUrl: args.apiUrl,
+        scryptSalt: args.scryptSalt,
+    });
+    await writeJwtFile(files.sessionFile, session.sessionJWT);
+    await writeJwtFile(files.capabilityFile, capabilityJWT);
+    log(`Wrote ${files.credentialsFile}`);
+    log(`Wrote ${files.sessionFile}`);
+    log(`Wrote ${files.capabilityFile}`);
+    process.stdout.write(JSON.stringify({
+        inboxId,
+        apiKey,
+        credentialsFile: files.credentialsFile,
+        sessionFile: files.sessionFile,
+        capabilityFile: files.capabilityFile,
+    }, null, 2) + "\n");
+}
+main().catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@atomicmail/agent-skill",
+  "version": "0.1.0",
+  "description": "Atomic Mail agent skill — PoW signup + JMAP request CLIs for AI agents.",
+  "keywords": [
+    "atomic-mail",
+    "atomicmail",
+    "agentskills",
+    "agent",
+    "ai",
+    "jmap",
+    "esp",
+    "email",
+    "mcp",
+    "proof-of-work"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atomic-mail/agentic-mail.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/atomic-mail/agentic-mail/issues"
+  },
+  "scripts": {},
+  "bin": {
+    "atomic-mail-signup": "./esm/skill/scripts/signup.js",
+    "atomic-mail-jmap": "./esm/skill/scripts/jmap_request.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0"
+  },
+  "_generatedBy": "dnt@dev"
+}