@atomicmail/agent-skill-openclaw 0.3.24

package/esm/lib/network/auth-client.js

@@ -0,0 +1,210 @@
+// Thin HTTP client for auth-service (PoW challenge → session → capability).
+//
+// Encapsulates the full PoW challenge → session → capability flow so callers
+// (integration tests, the future agent skill, etc.) don't have to reimplement scrypt grinding.
+//
+// The PoW digest is scrypt-based and uses the SAME salt the auth-service
+// uses on the verify path (see services/auth-service/src/crypto.ts). The
+// client must therefore be configured with that salt — there is no public
+// hash function here, the salt is part of the protocol.
+import { scrypt } from "node:crypto";
+import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../core/consts.js";
+// Mirror services/auth-service/src/crypto.ts exactly. Changing any of these
+// constants on either side breaks PoW interop.
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+const POW_HASH_BYTES = 64;
+/** Thrown for any non-2xx HTTP response or malformed payload. */
+export class AuthClientError extends Error {
+    status;
+    bodyText;
+    constructor(status, bodyText, message) {
+        super(message);
+        this.name = "AuthClientError";
+        this.status = status;
+        this.bodyText = bodyText;
+    }
+}
+export class AuthClient {
+    baseUrl;
+    scryptSaltHex;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.scryptSaltHex = options.scryptSaltHex ?? DEFAULT_POW_SCRYPT_SALT_HEX;
+    }
+    /**
+     * Register a new inbox under `username`. Returns the freshly minted API key
+     * (the server only ever returns it once — the caller MUST persist it) and
+     * a session JWT.
+     */
+    async signup(username) {
+        const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
+        const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
+        const { sessionJWT, data } = await this.postSession(challengeJWT, {
+            powHex,
+            nonce: nonce.toString(),
+            username,
+        });
+        if (typeof data.apiKey !== "string") {
+            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey.");
+        }
+        return { apiKey: data.apiKey, sessionJWT };
+    }
+    /** Exchange an existing API key for a fresh session JWT. */
+    async login(apiKey) {
+        const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
+        const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
+        const { sessionJWT } = await this.postSession(challengeJWT, {
+            powHex,
+            nonce: nonce.toString(),
+            apiKey,
+        });
+        return { sessionJWT };
+    }
+    /**
+     * Exchange a session JWT for a short-lived capability JWT (audience:
+     * api-service).
+     */
+    async renew(sessionJWT) {
+        const res = await fetch(`${this.baseUrl}/api/v1/capability`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${sessionJWT}` },
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service capability returned ${res.status}: ${text}`);
+        }
+        const capabilityJWT = readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
+        return { capabilityJWT };
+    }
+    async fetchChallenge() {
+        const res = await fetch(`${this.baseUrl}/api/v1/challenge`, {
+            method: "POST",
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service challenge returned ${res.status}: ${text}`);
+        }
+        const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+        const payload = decodeJwtPayload(challengeJWT);
+        if (typeof payload.jti !== "string" ||
+            typeof payload.difficulty !== "number") {
+            throw new AuthClientError(res.status, challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
+        }
+        return {
+            challengeJWT,
+            challenge: payload.jti,
+            difficulty: payload.difficulty,
+        };
+    }
+    async postSession(challengeJWT, body) {
+        const res = await fetch(`${this.baseUrl}/api/v1/session`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${challengeJWT}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service session returned ${res.status}: ${text}`);
+        }
+        const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+        let data = {};
+        if (text.trim().length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new AuthClientError(res.status, text, "auth-service session returned non-JSON body.");
+            }
+        }
+        return { sessionJWT, data };
+    }
+    async parseJsonOrThrow(res, endpoint) {
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service ${endpoint} returned ${res.status}: ${text}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new AuthClientError(res.status, text, `auth-service ${endpoint} returned non-JSON body.`);
+        }
+    }
+    /**
+     * Brute-force a PoW nonce. Mirrors `generatePow` in
+     * services/auth-service/src/crypto.ts: scrypt(`${challenge}:${nonce}`, salt,
+     * 64) until `difficulty` leading bits of the digest are zero.
+     *
+     * Expected work at the server's POW_DIFFICULTY=6 is ~2^6 = 64 attempts; well
+     * within the challenge JWT's 3-minute TTL.
+     */
+    async solvePoW(challenge, difficulty) {
+        let nonce = 0n;
+        while (true) {
+            const digest = await scryptHash(`${challenge}:${nonce}`, this.scryptSaltHex);
+            if (hasLeadingZeroBits(digest, difficulty)) {
+                return { powHex: bytesToHex(digest), nonce };
+            }
+            nonce++;
+        }
+    }
+}
+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));
+        });
+    });
+}
+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;
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+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));
+}
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

package/esm/package.json

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

package/esm/skill/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "../_dnt.polyfills.js";
+//# sourceMappingURL=cli.d.ts.map

package/esm/skill/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/skill/cli.ts"],"names":[],"mappings":";AAEA,OAAO,sBAAsB,CAAC"}

package/esm/skill/cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// Atomic Mail AgentSkill — register | jmap_request | help
+import "../_dnt.polyfills.js";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { AgentSession, DEFAULT_API_URL, DEFAULT_AUTH_URL, DEFAULT_JMAP_USING, DEFAULT_POW_SCRYPT_SALT_HEX, defaultFilesFromOutDir, expandCredentialDirInput, getHelp, parseUserVarsJson, persistLoginWithApiKey, readCredentials, readOpsFile, runJmapRequest, sharedError, } from "../lib/mod.js";
+const USAGE = `Atomic Mail — AgentSkill
+
+Usage:
+  atomicmail <command> [options]
+
+Commands:
+  register       PoW signup or login with API key (writes credentials)
+  jmap_request   Send a JMAP batch (inline --ops or --ops-file; optional --attachment)
+  help           Full documentation [--topic TOPIC] (topic readme = built-in stub)
+
+Examples:
+  atomicmail register --username alice
+  atomicmail register --api-key UUID
+  atomicmail jmap_request --ops-file list_inbox.json
+  atomicmail jmap_request --credentials-dir ./.atomic-mail --ops-file send.json --vars '{"TO":"a@b.com","SUBJECT":"Hi"}'
+  atomicmail jmap_request --ops-file send_mail_blob_attachment.json --attachment ./notes.txt --vars '{"TO":"self@example.com","SUBJECT":"File","BODY":"See attach."}'
+  atomicmail help --topic presets
+  atomicmail help --topic readme
+
+Call  atomicmail help  early and often — topics match this install; prefer help
+over guessing JMAP or preset details.
+
+Run  atomicmail <command> --help  for command-specific flags.
+`;
+function exitUsage(code = 0) {
+    process.stdout.write(USAGE);
+    process.exit(code);
+}
+function fail(message, code = 1) {
+    process.stderr.write(`Error: ${message}\n`);
+    process.exit(code);
+}
+async function cmdRegister(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                "auth-url": { type: "string" },
+                "api-url": { type: "string" },
+                "scrypt-salt": { type: "string" },
+                username: { type: "string" },
+                "api-key": { type: "string" },
+                "credentials-dir": { type: "string" },
+                forced: { type: "boolean" },
+                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(`Usage: atomicmail register [OPTIONS]
+
+Register a new inbox (--username) or log in with an existing API key (--api-key).
+
+Options:
+  --auth-url URL       Auth-service base URL [env: ATOMIC_MAIL_AUTH_URL, default: https://auth.atomicmail.ai]
+  --api-url URL        API / JMAP base URL [env: ATOMIC_MAIL_API_URL, default: https://api.atomicmail.ai]
+  --scrypt-salt SALT   PoW salt override [env: ATOMIC_MAIL_SCRYPT_SALT]
+  --username NAME      New account (5–21 characters; mutually exclusive with --api-key)
+  --api-key KEY        Existing API key (mutually exclusive with --username)
+  --credentials-dir DIR  Credential directory (default: ~/.atomicmail)
+  --forced             Allow replacing existing credentials with a new account
+  --quiet              Less stderr output
+  --help, -h           This message
+
+After register, arrange hourly inbox polling per your runtime (atomicmail help
+--topic cron): native cron hosts schedule an AGENT turn with list_inbox.json;
+no-native-cron hosts ask the operator or remind manual fetch — do not work
+around with OS crontab or cross-platform scheduling. Do NOT cron atomicmail
+jmap_request alone.
+`);
+        process.exit(0);
+    }
+    const env = process.env;
+    const authUrl = parsed.values["auth-url"] ??
+        env.ATOMIC_MAIL_AUTH_URL ?? DEFAULT_AUTH_URL;
+    const apiUrl = parsed.values["api-url"] ??
+        env.ATOMIC_MAIL_API_URL ?? DEFAULT_API_URL;
+    const scryptSalt = parsed.values["scrypt-salt"] ??
+        env.ATOMIC_MAIL_SCRYPT_SALT ?? DEFAULT_POW_SCRYPT_SALT_HEX;
+    const dir = parsed.values["credentials-dir"];
+    const credentialDir = expandCredentialDirInput(dir);
+    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);
+    }
+    const files = defaultFilesFromOutDir(credentialDir);
+    const log = (msg) => {
+        if (!parsed.values.quiet)
+            process.stderr.write(msg + "\n");
+    };
+    if (username) {
+        log(`Registering "${username}"...`);
+        const session = await AgentSession.create({
+            authUrl,
+            apiUrl,
+            scryptSalt,
+            credentialDir,
+            files,
+        });
+        const result = await session.register(username, {
+            forced: parsed.values.forced === true,
+        });
+        log(`Wrote credentials under ${credentialDir}`);
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return;
+    }
+    log("Logging in with API key...");
+    const { inboxId } = await persistLoginWithApiKey({
+        authUrl,
+        apiUrl,
+        scryptSalt,
+        apiKey: apiKey,
+        files,
+    });
+    log(`Wrote ${files.credentialsFile}`);
+    process.stdout.write(JSON.stringify({ inboxId }, null, 2) + "\n");
+}
+async function cmdJmapRequest(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            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" },
+                "dry-run": { type: "boolean" },
+                vars: { type: "string" },
+                attachment: { type: "string", multiple: true },
+                "attachment-path-base": { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        fail(err.message, 2);
+    }
+    if (parsed.values.help) {
+        process.stdout.write(`Usage: atomicmail jmap_request [OPTIONS]
+
+Send a JMAP request using saved credentials.
+
+Options:
+  --credentials-dir DIR      Directory with credentials.json + JWTs (default: ~/.atomicmail)
+  --credentials-file PATH    Override credentials.json path
+  --session-file PATH        Override session.jwt path
+  --capability-file PATH     Override capability.jwt path
+  --ops JSON                 Inline JMAP JSON (methodCalls or envelope)
+  --ops-file PATH            Preset file ($VAR_NAME placeholders supported)
+  --vars JSON                JSON object { VAR_NAME: string } for $VAR_NAME in ops / ops-file
+  --attachment PATH          Repeatable; each file is RFC 8620–uploaded before JMAP (injects $ATTACHMENT_N_*)
+  --attachment-path-base DIR Base for relative --attachment paths (default: cwd)
+  --using LIST               Comma-separated capability URNs (optional)
+  --dry-run                  Print resolved request only (not compatible with --attachment)
+  --help, -h                 This message
+`);
+        process.exit(0);
+    }
+    const dir = parsed.values["credentials-dir"];
+    const credentialDir = expandCredentialDirInput(dir);
+    const defaults = defaultFilesFromOutDir(credentialDir);
+    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"];
+    if (ops && opsFile) {
+        fail(sharedError("cli_ops_mutually_exclusive"), 2);
+    }
+    if (!ops && !opsFile) {
+        fail(sharedError("cli_ops_required"), 2);
+    }
+    const rawAttachments = parsed.values.attachment;
+    const attachmentPaths = rawAttachments === undefined
+        ? []
+        : Array.isArray(rawAttachments)
+            ? rawAttachments
+            : [rawAttachments];
+    if (parsed.values["dry-run"] === true && attachmentPaths.length > 0) {
+        fail(sharedError("cli_dry_run_with_attachment"), 2);
+    }
+    const usingFlag = parsed.values.using;
+    const defaultUsing = usingFlag
+        ? usingFlag.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
+        : [...DEFAULT_JMAP_USING];
+    let userVars;
+    const varsFlag = parsed.values.vars;
+    if (varsFlag !== undefined) {
+        try {
+            userVars = parseUserVarsJson(varsFlag);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err), 2);
+        }
+    }
+    const creds = await readCredentials(credentialsFile);
+    const files = {
+        credentialsFile,
+        sessionFile,
+        capabilityFile,
+    };
+    const session = await AgentSession.create({
+        authUrl: creds.authUrl,
+        apiUrl: creds.apiUrl,
+        scryptSalt: creds.scryptSalt,
+        apiKey: creds.apiKey,
+        inboxId: creds.inboxId,
+        credentialDir,
+        files,
+    });
+    let raw;
+    let sourceLabel;
+    if (opsFile) {
+        try {
+            raw = await readOpsFile(credentialDir, opsFile);
+        }
+        catch (err) {
+            fail(`Could not read --ops-file: ${err.message}`, 2);
+        }
+        sourceLabel = `ops_file '${opsFile}'`;
+    }
+    else {
+        raw = ops;
+        sourceLabel = "ops";
+    }
+    const attachmentPathBase = parsed.values["attachment-path-base"];
+    // Same JMAP path as MCP: built-in `$INBOX` is normalized to a full mailbox
+    // address via shared `runJmapRequest` (see `inboxIdToMailboxEmail`).
+    const { ok, status, bodyText } = await runJmapRequest({
+        session,
+        opsJson: raw,
+        defaultUsing,
+        sourceLabel,
+        dryRun: parsed.values["dry-run"] === true,
+        vars: userVars,
+        attachments: attachmentPaths.length > 0
+            ? attachmentPaths.map((path) => ({ path }))
+            : undefined,
+        attachmentPathBase,
+    });
+    if (!ok) {
+        fail(`JMAP request failed (HTTP ${status}): ${bodyText}`, 1);
+    }
+    process.stdout.write(bodyText.endsWith("\n") ? bodyText : bodyText + "\n");
+}
+async function cmdHelp(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                topic: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        fail(err.message, 2);
+    }
+    if (parsed.values.help) {
+        process.stdout.write(`Usage: atomicmail help [--topic TOPIC]
+
+Topics include: overview, installation, auth, jmap_cheatsheet, tools, presets, troubleshooting, readme.
+Topic readme prints the built-in SKILL stub.
+`);
+        process.exit(0);
+    }
+    const topic = parsed.values.topic;
+    process.stdout.write(await getHelp(topic, "skill") + "\n");
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+        exitUsage(0);
+    }
+    const cmd = argv[0];
+    const rest = argv.slice(1);
+    switch (cmd) {
+        case "register":
+            await cmdRegister(rest);
+            break;
+        case "jmap_request":
+            await cmdJmapRequest(rest);
+            break;
+        case "help":
+            await cmdHelp(rest);
+            break;
+        default:
+            process.stderr.write(`Unknown command: ${cmd}\n\n`);
+            process.stdout.write(USAGE);
+            process.exit(2);
+    }
+}
+main().catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@atomicmail/agent-skill-openclaw",
+  "version": "0.3.24",
+  "description": "Atomic Mail AgentSkill — register, jmap_request, and help CLI for AI agents. (openclaw install channel)",
+  "keywords": [
+    "atomic-mail",
+    "atomicmail",
+    "agentskills",
+    "agent",
+    "ai",
+    "jmap",
+    "esp",
+    "email",
+    "mcp",
+    "proof-of-work",
+    "openclaw"
+  ],
+  "author": "Atomic Mail",
+  "homepage": "https://atomicmail.ai?utm_source=npm&utm_medium=package&utm_campaign=openclaw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atomic-Mail/atomic-mail-agentic.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Atomic-Mail/atomic-mail-agentic/issues"
+  },
+  "scripts": {},
+  "bin": {
+    "atomicmail": "./esm/skill/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "atomicmail": {
+    "channel": "openclaw"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/presets/list_inbox.json

@@ -0,0 +1,46 @@
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail"
+  ],
+  "methodCalls": [
+    [
+      "Email/query",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "filter": {
+          "inMailbox": "$INBOX_MAILBOX_ID"
+        },
+        "sort": [
+          {
+            "property": "receivedAt",
+            "isAscending": false
+          }
+        ],
+        "limit": 50
+      },
+      "q0"
+    ],
+    [
+      "Email/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "#ids": {
+          "resultOf": "q0",
+          "name": "Email/query",
+          "path": "/ids"
+        },
+        "properties": [
+          "id",
+          "threadId",
+          "receivedAt",
+          "from",
+          "to",
+          "subject",
+          "preview"
+        ]
+      },
+      "g0"
+    ]
+  ]
+}