enigma-memory 0.1.0

package/scripts/build-cloudflare-token-policy.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { buildCloudflareRequestPlan } from './cloudflare-ops.mjs';
+
+export const CLOUDFLARE_TOKEN_POLICY_SCHEMA = 'enigma.cloudflare_token_policy.v1';
+
+const SECRET_OUTPUT_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|cf-[A-Za-z0-9_-]{12,})/iu;
+const MODES = Object.freeze(['pages-deploy', 'pages-observe', 'domain-registrar', 'hosted-probe', 'all']);
+
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+function requireText(name, value) {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new UsageError(`${name} is required`);
+  return value.trim();
+}
+
+function optionalText(value, fallback = null) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function parseArgs(argv) {
+  const out = {
+    mode: 'pages-deploy',
+    accountId: '<cloudflare-account-id>',
+    projectName: 'enigma-memory',
+    domain: 'enigmamemory.com',
+    out: null,
+  };
+  for (let index = 0; index < argv.length;) {
+    const token = argv[index];
+    if (token === '--help') return { help: true };
+    const readValue = (name) => {
+      if (index + 1 >= argv.length || argv[index + 1].startsWith('--')) throw new UsageError(`${name} requires a value`);
+      const value = argv[index + 1];
+      index += 2;
+      return value;
+    };
+    if (token === '--mode') out.mode = readValue(token);
+    else if (token === '--account-id') out.accountId = readValue(token);
+    else if (token === '--project-name') out.projectName = readValue(token);
+    else if (token === '--domain') out.domain = readValue(token);
+    else if (token === '--out') out.out = readValue(token);
+    else throw new UsageError(`unknown option ${token}`);
+  }
+  return out;
+}
+
+function usage() {
+  return `Usage: node scripts/build-cloudflare-token-policy.mjs [options]\n\nOptions:\n  --mode <pages-deploy|pages-observe|domain-registrar|hosted-probe|all>  Default: pages-deploy.\n  --account-id <id>                                                     Account scope placeholder/default.\n  --project-name <name>                                                 Pages project. Default: enigma-memory.\n  --domain <host>                                                       Domain. Default: enigmamemory.com.\n  --out <file>                                                          Write JSON and print the same JSON.\n\nThis prints a public-safe API-token policy packet for the Cloudflare dashboard.\nIt lists intended permission groups and endpoints only; it never creates or prints a token.\n`;
+}
+
+function permission(id, product, permission_name, access, resource, reason) {
+  return { id, product, permission_name, access, resource, reason, operator_must_map_to_permission_group_id: true };
+}
+
+function includeMode(mode, candidate) {
+  return mode === 'all' || mode === candidate;
+}
+
+function plannedApiCalls({ mode, accountId, projectName, domain }) {
+  const calls = [];
+  calls.push(buildCloudflareRequestPlan({ operation: 'token.verify', accountId }));
+  if (includeMode(mode, 'pages-observe') || includeMode(mode, 'pages-deploy')) {
+    calls.push(buildCloudflareRequestPlan({ operation: 'pages.project', accountId, projectName }));
+  }
+  if (includeMode(mode, 'domain-registrar')) {
+    calls.push(buildCloudflareRequestPlan({ operation: 'registrar.search', accountId, query: domain, limit: 5 }));
+    calls.push(buildCloudflareRequestPlan({ operation: 'registrar.check', accountId, domain }));
+    calls.push(buildCloudflareRequestPlan({ operation: 'registrar.register', accountId, domain }));
+    calls.push(buildCloudflareRequestPlan({ operation: 'registrar.registration-status', accountId, domain }));
+  }
+  if (includeMode(mode, 'hosted-probe')) {
+    for (const service of ['enigma-hosted-probe', 'enigma-relay', 'enigma-gateway']) {
+      calls.push({
+        operation: 'workers.service.upsert',
+        method: 'PUT',
+        path: `/client/v4/accounts/${accountId}/workers/services/${service}`,
+        requires_token: true,
+        token_printed: false,
+        billable: false,
+      });
+    }
+    calls.push({
+      operation: 'workers.custom-domains.attach',
+      method: 'PUT',
+      path: `/client/v4/accounts/${accountId}/workers/domains`,
+      requires_token: true,
+      token_printed: false,
+      billable: false,
+    });
+    calls.push({
+      operation: 'workers.custom-domains.list',
+      method: 'GET',
+      path: `/client/v4/accounts/${accountId}/workers/domains`,
+      requires_token: true,
+      token_printed: false,
+      billable: false,
+    });
+  }
+  return calls.map((call) => ({
+    operation: call.operation,
+    method: call.method,
+    path: call.path ?? new URL(call.url).pathname,
+    requires_token: call.requires_token ?? call.requiresToken === true,
+    token_printed: call.token_printed ?? call.tokenPrinted === true,
+    billable: call.billable === true,
+  }));
+}
+
+function permissionPolicy({ mode, accountId, projectName, domain }) {
+  const permissions = [
+    permission('token_verify', 'User/API Tokens', 'API Tokens Read', 'read', 'own token', 'Verify the token without exposing its value.'),
+  ];
+  if (includeMode(mode, 'pages-observe')) {
+    permissions.push(
+      permission('account_read', 'Account', 'Account Settings Read', 'read', `account:${accountId}`, 'Confirm account/project ownership.'),
+      permission('pages_read', 'Cloudflare Pages', 'Cloudflare Pages Read', 'read', `account:${accountId}/pages/${projectName}`, 'Observe Pages project and custom-domain state.')
+    );
+  }
+  if (includeMode(mode, 'pages-deploy')) {
+    permissions.push(
+      permission('account_read', 'Account', 'Account Settings Read', 'read', `account:${accountId}`, 'Confirm account/project ownership.'),
+      permission('pages_edit', 'Cloudflare Pages', 'Cloudflare Pages Edit', 'edit', `account:${accountId}/pages/${projectName}`, 'Deploy the preflighted static artifact to Pages.')
+    );
+  }
+  if (includeMode(mode, 'domain-registrar')) {
+    permissions.push(
+      permission('registrar_read', 'Registrar', 'Registrar Read', 'read', `account:${accountId}/registrar/${domain}`, 'Search/check domain and read registration status.'),
+      permission('registrar_edit', 'Registrar', 'Registrar Edit', 'edit', `account:${accountId}/registrar/${domain}`, 'Register the exact confirmed domain after explicit charge acknowledgement.')
+    );
+  }
+  if (includeMode(mode, 'hosted-probe')) {
+    permissions.push(
+      permission('workers_scripts_read', 'Workers Scripts', 'Workers Scripts Read', 'read', `account:${accountId}/workers/enigma-hosted-probe,enigma-relay,enigma-gateway`, 'Observe hosted probe and relay/gateway Worker services before/after deploy.'),
+      permission('workers_scripts_edit', 'Workers Scripts', 'Workers Scripts Edit', 'edit', `account:${accountId}/workers/enigma-hosted-probe,enigma-relay,enigma-gateway`, 'Deploy the hosted probe plus relay/gateway /livez and fail-closed /readyz Workers.'),
+      permission('workers_routes_edit', 'Workers Routes', 'Workers Routes Edit', 'edit', `zone:${domain}/workers/custom-domains`, 'Attach relay.enigmamemory.com and gateway.enigmamemory.com as Workers Custom Domains without printing token values.')
+    );
+  }
+  const unique = new Map();
+  for (const item of permissions) unique.set(`${item.permission_name}:${item.access}:${item.resource}`, item);
+  return [...unique.values()];
+}
+
+function environmentContract({ mode }) {
+  const env = [
+    { name: 'CLOUDFLARE_API_TOKEN', secret: true, required: true, handling: 'Store in a secret manager or process environment only; never paste into chat, docs, or repo files.' },
+    { name: 'CLOUDFLARE_ACCOUNT_ID', secret: false, required: true, handling: 'Account id is not a token but still belongs in operator config, not public marketing collateral.' },
+  ];
+  if (includeMode(mode, 'domain-registrar')) {
+    env.push({ name: 'REGISTRANT_CONTACT_JSON', secret: true, required: 'only for registration execution', handling: 'One-use local file; never commit. Command output redacts contact body fields.' });
+  }
+  return env;
+}
+
+export function buildCloudflareTokenPolicy(input = {}) {
+  const mode = requireText('--mode', input.mode ?? 'pages-deploy');
+  if (!MODES.includes(mode)) throw new UsageError(`--mode must be one of ${MODES.join(', ')}`);
+  const accountId = optionalText(input.accountId, '<cloudflare-account-id>');
+  const projectName = optionalText(input.projectName, 'enigma-memory');
+  const domain = optionalText(input.domain, 'enigmamemory.com');
+  const verificationCommands = [
+    'npm run cloudflare:ops -- token verify --account-id <account-id>',
+    'npm run cloudflare:pages:packet -- --site ../github-upload/enigma-memory-site/_public_site --project-name enigma-memory --domain enigmamemory.com --live-url https://enigmamemory.com/ --expect-title Enigma',
+    'npm run production:handoff -- --site ../github-upload/enigma-memory-site/_public_site --project-name enigma-memory --domain enigmamemory.com --live-url https://enigmamemory.com/ --expect-title Enigma',
+  ];
+  if (includeMode(mode, 'hosted-probe')) {
+    verificationCommands.splice(1, 0, 'npm run cloudflare:ops -- workers inspect-probe --name enigma-hosted-probe');
+    verificationCommands.splice(2, 0, 'npm run production:edge-backend -- --out-dir .enigma/edge-backend-workers --domain enigmamemory.com');
+  }
+  return {
+    schema: CLOUDFLARE_TOKEN_POLICY_SCHEMA,
+    generated_at: input.generated_at ?? input.generatedAt ?? new Date().toISOString(),
+    mode,
+    target: {
+      account_id: accountId,
+      pages_project: projectName,
+      domain,
+    },
+    credential_contract: environmentContract({ mode }),
+    permission_groups: permissionPolicy({ mode, accountId, projectName, domain }),
+    planned_api_calls: plannedApiCalls({ mode, accountId, projectName, domain }),
+    mutation_boundaries: {
+      pages_deploy_requires_execute: true,
+      registrar_register_requires_execute: true,
+      workers_deploy_probe_requires_execute: true,
+      registrar_register_requires_charge_acknowledgement: true,
+      registrar_register_requires_fresh_price_check: true,
+      token_value_printed: false,
+      personal_contact_printed: false,
+    },
+    dashboard_steps: [
+      'Cloudflare Dashboard -> My Profile -> API Tokens -> Create Token -> Custom token.',
+      'Set account scope to the target account only; do not grant all accounts unless an operator explicitly approves it.',
+      'Map each listed permission name to Cloudflare permission-group IDs shown by the dashboard or /user/tokens/permission_groups.',
+      'Copy the token directly into a secret manager or process environment as CLOUDFLARE_API_TOKEN; do not paste it into chat.',
+      'Run token verify, then the dry-run packet, then execute deploy only after local site preflight/security gates pass.',
+    ],
+    verification_commands: verificationCommands,
+    claim_boundary: [
+      'This packet is a least-privilege Cloudflare token policy, not an API token and not proof a token exists.',
+      'Permission display names must be mapped to Cloudflare permission_group IDs in the logged-in dashboard or API response.',
+      'Pages deployment and domain registration remain dry-run unless --execute and all explicit safety confirmations are supplied.',
+      'Worker probe deployment remains dry-run unless --execute is supplied; token policy generation never deploys a Worker.',
+    ],
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return { text: usage() };
+  const packet = buildCloudflareTokenPolicy({ ...parsed, generated_at: options.generated_at ?? options.generatedAt });
+  const json = `${JSON.stringify(packet, null, 2)}\n`;
+  if (SECRET_OUTPUT_RE.test(json)) throw new Error('Cloudflare token policy output appears to contain a secret');
+  if (parsed.out) {
+    const outPath = resolve(parsed.out);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, json, 'utf8');
+  }
+  return { json: packet };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await runCli();
+    if (result.text) process.stdout.write(result.text);
+    else process.stdout.write(`${JSON.stringify(result.json, null, 2)}\n`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(`${JSON.stringify({ schema: CLOUDFLARE_TOKEN_POLICY_SCHEMA, ok: false, error: { code: error instanceof UsageError ? 'USAGE_ERROR' : 'TOKEN_POLICY_ERROR', message } }, null, 2)}\n`);
+    process.exitCode = error instanceof UsageError ? 2 : 1;
+  }
+}

package/scripts/build-cloudflare-token-request.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const CLOUDFLARE_TOKEN_REQUEST_SCHEMA = 'enigma.cloudflare_token_request.v1';
+
+const SECRET_OUTPUT_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|cf-[A-Za-z0-9_-]{12,})/iu;
+const MODES = Object.freeze(['pages-deploy', 'pages-observe', 'domain-registrar', 'hosted-probe', 'all']);
+const ACCOUNT_SCOPE = 'com.cloudflare.api.account';
+const ZONE_SCOPE = 'com.cloudflare.api.account.zone';
+const USER_SCOPE = 'com.cloudflare.api.user';
+
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const out = {
+    mode: 'pages-deploy',
+    accountId: null,
+    userId: null,
+    permissionGroups: null,
+    projectName: 'enigma-memory',
+    domain: 'enigmamemory.com',
+    tokenName: 'enigma-memory-pages-deploy',
+    out: null,
+  };
+  for (let index = 0; index < argv.length;) {
+    const token = argv[index];
+    if (token === '--help') return { help: true };
+    const readValue = (name) => {
+      if (index + 1 >= argv.length || argv[index + 1].startsWith('--')) throw new UsageError(`${name} requires a value`);
+      const value = argv[index + 1];
+      index += 2;
+      return value;
+    };
+    if (token === '--mode') out.mode = readValue(token);
+    else if (token === '--account-id') out.accountId = readValue(token);
+    else if (token === '--user-id') out.userId = readValue(token);
+    else if (token === '--permission-groups') out.permissionGroups = readValue(token);
+    else if (token === '--project-name') out.projectName = readValue(token);
+    else if (token === '--domain') out.domain = readValue(token);
+    else if (token === '--token-name') out.tokenName = readValue(token);
+    else if (token === '--out') out.out = readValue(token);
+    else throw new UsageError(`unknown option ${token}`);
+  }
+  return out;
+}
+
+function usage() {
+  return `Usage: node scripts/build-cloudflare-token-request.mjs --permission-groups <json> --account-id <id> [options]\n\nOptions:\n  --mode <pages-deploy|pages-observe|domain-registrar|hosted-probe|all>  Default: pages-deploy.\n  --project-name <name>                                                 Default: enigma-memory.\n  --domain <host>                                                       Default: enigmamemory.com.\n  --token-name <name>                                                   Default: enigma-memory-pages-deploy.\n  --user-id <id>                                                        Only needed if adding user-scoped permissions.\n  --out <file>                                                          Write JSON and print the same JSON.\n\nInput should be the JSON returned by Cloudflare /user/tokens/permission_groups. The output is a request-body skeleton; it does not create or print a token.\n`;
+}
+
+function requiredText(name, value) {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new UsageError(`${name} is required`);
+  return value.trim();
+}
+
+function normalize(value) {
+  return String(value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().replace(/\s+/g, ' ');
+}
+
+function includeMode(mode, candidate) {
+  return mode === 'all' || mode === candidate;
+}
+
+function permissionSpecs(mode) {
+  const specs = [];
+  if (includeMode(mode, 'pages-observe') || includeMode(mode, 'pages-deploy')) {
+    specs.push({
+      key: 'account_read',
+      access: 'read',
+      product: 'Account',
+      aliases: ['Account Settings Read', 'Account:Read', 'Account Read'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Confirm account/project ownership before deploy or verify.',
+    });
+    specs.push({
+      key: 'pages_read',
+      access: 'read',
+      product: 'Cloudflare Pages',
+      aliases: ['Cloudflare Pages Read', 'Pages Read'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Read Pages project/custom-domain state during verification.',
+    });
+  }
+  if (includeMode(mode, 'pages-deploy')) {
+    specs.push({
+      key: 'pages_edit',
+      access: 'edit',
+      product: 'Cloudflare Pages',
+      aliases: ['Cloudflare Pages Edit', 'Cloudflare Pages Write', 'Cloudflare Pages:Edit', 'Pages Edit', 'Pages Write'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Deploy the preflighted static artifact to Cloudflare Pages.',
+    });
+  }
+  if (includeMode(mode, 'domain-registrar')) {
+    specs.push({
+      key: 'registrar_read',
+      access: 'read',
+      product: 'Registrar',
+      aliases: ['Registrar Read', 'Domain Registration Read', 'Registrar Domains Read'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Search/check domain registration and read registration status.',
+    });
+    specs.push({
+      key: 'registrar_edit',
+      access: 'edit',
+      product: 'Registrar',
+      aliases: ['Registrar Edit', 'Registrar Write', 'Domain Registration Edit', 'Domain Registration Write', 'Registrar Domains Edit', 'Registrar Domains Write'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Register the exact confirmed domain only after charge acknowledgement.',
+    });
+  }
+  if (includeMode(mode, 'hosted-probe')) {
+    specs.push({
+      key: 'workers_scripts_read',
+      access: 'read',
+      product: 'Workers Scripts',
+      aliases: ['Workers Scripts Read', 'Workers Read', 'Cloudflare Workers Read', 'Workers Script Read'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Observe hosted probe and relay/gateway Worker services before/after deploy.',
+    });
+    specs.push({
+      key: 'workers_scripts_edit',
+      access: 'edit',
+      product: 'Workers Scripts',
+      aliases: ['Workers Scripts Edit', 'Workers Scripts Write', 'Workers Edit', 'Workers Write', 'Cloudflare Workers Edit', 'Cloudflare Workers Write', 'Workers Script Edit'],
+      preferred_scope: ACCOUNT_SCOPE,
+      reason: 'Deploy the hosted /livez and fail-closed /readyz probe plus relay/gateway edge Workers.',
+    });
+    specs.push({
+      key: 'workers_routes_edit',
+      access: 'edit',
+      product: 'Workers Routes',
+      aliases: ['Workers Routes Edit', 'Workers Routes Write', 'Cloudflare Workers Routes Edit', 'Workers Route Edit'],
+      preferred_scope: ZONE_SCOPE,
+      reason: 'Attach relay.enigmamemory.com and gateway.enigmamemory.com as Workers Custom Domains without exposing token values.',
+    });
+  }
+  return specs;
+}
+
+function extractPermissionGroups(raw) {
+  const parsed = Array.isArray(raw) ? raw : (Array.isArray(raw?.result) ? raw.result : raw?.result?.permission_groups);
+  if (!Array.isArray(parsed)) throw new UsageError('permission group JSON must be an array or contain result[]');
+  return parsed.map((item, index) => {
+    if (typeof item?.id !== 'string' || item.id.trim().length === 0) throw new UsageError(`permission group at index ${index} missing id`);
+    if (typeof item?.name !== 'string' || item.name.trim().length === 0) throw new UsageError(`permission group at index ${index} missing name`);
+    const scopes = Array.isArray(item.scopes) ? item.scopes.filter((scope) => typeof scope === 'string') : [];
+    return {
+      id: item.id.trim(),
+      name: item.name.trim(),
+      description: typeof item.description === 'string' ? item.description.trim() : '',
+      scopes,
+    };
+  });
+}
+
+function chooseCandidate(candidates, preferredScope) {
+  const scoped = candidates.find((candidate) => candidate.scopes.includes(preferredScope));
+  return scoped ?? candidates[0] ?? null;
+}
+
+function resolvePermissions(groups, specs) {
+  const byName = new Map();
+  for (const group of groups) {
+    const key = normalize(group.name);
+    if (!byName.has(key)) byName.set(key, []);
+    byName.get(key).push(group);
+  }
+  const resolved = [];
+  const unresolved = [];
+  for (const spec of specs) {
+    let match = null;
+    for (const alias of spec.aliases) {
+      const candidates = byName.get(normalize(alias));
+      if (candidates?.length) {
+        match = chooseCandidate(candidates, spec.preferred_scope);
+        break;
+      }
+    }
+    if (match === null) {
+      unresolved.push({ key: spec.key, aliases: spec.aliases, preferred_scope: spec.preferred_scope, reason: spec.reason });
+    } else {
+      resolved.push({
+        key: spec.key,
+        id: match.id,
+        name: match.name,
+        scopes: match.scopes,
+        access: spec.access,
+        product: spec.product,
+        reason: spec.reason,
+      });
+    }
+  }
+  return { resolved, unresolved };
+}
+
+function resourceForScope(scope, { accountId, userId }) {
+  if (scope === ACCOUNT_SCOPE) return { resource: `com.cloudflare.api.account.${accountId}`, value: '*' };
+  if (scope === ZONE_SCOPE) return { resource: `com.cloudflare.api.account.${accountId}`, value: { 'com.cloudflare.api.account.zone.*': '*' } };
+  if (scope === USER_SCOPE) return userId ? { resource: `com.cloudflare.api.user.${userId}`, value: '*' } : null;
+  return null;
+}
+
+function policiesForResolved(resolved, context) {
+  const buckets = new Map();
+  const missingResources = [];
+  for (const item of resolved) {
+    const scope = item.scopes.includes(ACCOUNT_SCOPE) ? ACCOUNT_SCOPE
+      : item.scopes.includes(ZONE_SCOPE) ? ZONE_SCOPE
+      : item.scopes.includes(USER_SCOPE) ? USER_SCOPE
+      : item.scopes[0];
+    const resource = resourceForScope(scope, context);
+    if (resource === null) {
+      missingResources.push({ key: item.key, id: item.id, name: item.name, scope });
+      continue;
+    }
+    const bucketKey = `${scope}:${JSON.stringify(resource)}`;
+    if (!buckets.has(bucketKey)) buckets.set(bucketKey, { scope, resources: { [resource.resource]: resource.value }, permission_groups: [] });
+    buckets.get(bucketKey).permission_groups.push({ id: item.id, name: item.name });
+  }
+  const policies = [...buckets.values()].map((bucket) => ({
+    effect: 'allow',
+    resources: bucket.resources,
+    permission_groups: bucket.permission_groups.sort((a, b) => a.name.localeCompare(b.name)),
+  }));
+  return { policies, missingResources };
+}
+
+async function readPermissionGroups(path) {
+  return JSON.parse(await readFile(resolve(path), 'utf8'));
+}
+
+export async function buildCloudflareTokenRequest(input = {}) {
+  const mode = requiredText('--mode', input.mode ?? 'pages-deploy');
+  if (!MODES.includes(mode)) throw new UsageError(`--mode must be one of ${MODES.join(', ')}`);
+  const accountId = requiredText('--account-id', input.accountId);
+  const tokenName = requiredText('--token-name', input.tokenName ?? 'enigma-memory-pages-deploy');
+  const rawGroups = input.permissionGroupsJson ?? await readPermissionGroups(requiredText('--permission-groups', input.permissionGroups));
+  const groups = extractPermissionGroups(rawGroups);
+  const specs = permissionSpecs(mode);
+  const { resolved, unresolved } = resolvePermissions(groups, specs);
+  const { policies, missingResources } = policiesForResolved(resolved, { accountId, userId: input.userId });
+  const tokenRequest = {
+    name: tokenName,
+    policies,
+  };
+  const ok = unresolved.length === 0 && missingResources.length === 0 && policies.length > 0;
+  const output = {
+    schema: CLOUDFLARE_TOKEN_REQUEST_SCHEMA,
+    generated_at: input.generated_at ?? input.generatedAt ?? new Date().toISOString(),
+    ok,
+    mode,
+    account_id: accountId,
+    token_name: tokenName,
+    required_permission_count: specs.length,
+    resolved_permission_count: resolved.length,
+    unresolved_permission_count: unresolved.length,
+    resolved_permission_groups: resolved,
+    unresolved_permission_groups: unresolved,
+    missing_resource_bindings: missingResources,
+    token_request: tokenRequest,
+    create_endpoints: {
+      account_owned_token: `/client/v4/accounts/${accountId}/tokens`,
+      user_owned_token: '/client/v4/user/tokens',
+    },
+    mutation_boundaries: {
+      token_created: false,
+      token_value_printed: false,
+      requires_api_tokens_edit_bootstrap_token_for_api_creation: true,
+      dashboard_creation_supported: true,
+      registrar_register_requires_charge_acknowledgement: includeMode(mode, 'domain-registrar'),
+    },
+    source_notes: [
+      'Cloudflare token policies use permission group ids; permission names are cosmetic and may change.',
+      'Account resources use com.cloudflare.api.account.<ACCOUNT_ID>: "*" for account-scoped permissions.',
+      'This packet is a request body skeleton only; it does not create a token or prove credentials exist.',
+    ],
+  };
+  const json = JSON.stringify(output);
+  if (SECRET_OUTPUT_RE.test(json)) throw new Error('Cloudflare token request output appears to contain a secret');
+  return output;
+}
+
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return { text: usage() };
+  const packet = await buildCloudflareTokenRequest({ ...parsed, generated_at: options.generated_at ?? options.generatedAt });
+  const json = `${JSON.stringify(packet, null, 2)}\n`;
+  if (parsed.out) {
+    const outPath = resolve(parsed.out);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, json, 'utf8');
+  }
+  return { json: packet };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await runCli();
+    if (result.text) process.stdout.write(result.text);
+    else process.stdout.write(`${JSON.stringify(result.json, null, 2)}\n`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(`${JSON.stringify({ schema: CLOUDFLARE_TOKEN_REQUEST_SCHEMA, ok: false, error: { code: error instanceof UsageError ? 'USAGE_ERROR' : 'TOKEN_REQUEST_ERROR', message } }, null, 2)}\n`);
+    process.exitCode = error instanceof UsageError ? 2 : 1;
+  }
+}