@heyanon-arp/sdk 0.0.26 → 0.0.29

package/dist/index.js

@@ -579,6 +579,40 @@ var CliLoginSessionStates = {
 
 // src/types/agent.ts
 var AGENT_TAG_REGEX = /^[a-z0-9][a-z0-9_-]{0,38}[a-z0-9]$|^[a-z0-9]$/;
+var AGENT_NAME_REGEX = /^[a-z0-9_]{3,32}$/;
+function normalizeName(input) {
+  return input.trim().replace(/^@+/, "").trim().toLowerCase();
+}
+var RESERVED_NAMES = [
+  "admin",
+  "administrator",
+  "system",
+  "root",
+  "owner",
+  "operator",
+  "did",
+  "arp",
+  "heyarp",
+  "heyanon",
+  "anon",
+  "self",
+  "you",
+  "null",
+  "undefined",
+  "none",
+  "api",
+  "www",
+  "support",
+  "help",
+  "info"
+];
+var RESERVED_NAME_SET = new Set(RESERVED_NAMES);
+function isReservedName(name) {
+  return RESERVED_NAME_SET.has(normalizeName(name));
+}
+function isValidAgentName(name) {
+  return AGENT_NAME_REGEX.test(normalizeName(name));
+}
 
 // src/assets.ts
 var SOLANA_CLUSTER_IDS = {
@@ -964,6 +998,7 @@ var CliAuthTokenErrorCodes = {
   REQUIRED: "AUTH_TOKEN_REQUIRED"
 };
 
+exports.AGENT_NAME_REGEX = AGENT_NAME_REGEX;
 exports.AGENT_TAG_REGEX = AGENT_TAG_REGEX;
 exports.ASSET_DECIMALS_MAX = ASSET_DECIMALS_MAX;
 exports.ASSET_DECIMALS_MIN = ASSET_DECIMALS_MIN;
@@ -1024,6 +1059,7 @@ exports.Purpose = Purpose;
 exports.READ_MODEL_STATUSES = READ_MODEL_STATUSES;
 exports.RECEIPT_VERDICTS = RECEIPT_VERDICTS;
 exports.RELATIONSHIP_STATE_NAMES = RELATIONSHIP_STATE_NAMES;
+exports.RESERVED_NAMES = RESERVED_NAMES;
 exports.ReadModelStatuses = ReadModelStatuses;
 exports.ReceiptVerdicts = ReceiptVerdicts;
 exports.RelationshipStates = RelationshipStates;
@@ -1078,11 +1114,14 @@ exports.isPostCommitErrorCode = isPostCommitErrorCode;
 exports.isReadModelStatus = isReadModelStatus;
 exports.isReceiptVerdict = isReceiptVerdict;
 exports.isRelationshipState = isRelationshipState;
+exports.isReservedName = isReservedName;
 exports.isSha256Hex = isSha256Hex;
+exports.isValidAgentName = isValidAgentName;
 exports.isValidDid = isValidDid;
 exports.isWhitelistedAssetId = isWhitelistedAssetId;
 exports.isWorkLogState = isWorkLogState;
 exports.listWhitelistedAssets = listWhitelistedAssets;
+exports.normalizeName = normalizeName;
 exports.parseCaip19SolanaAssetId = parseCaip19SolanaAssetId;
 exports.parseDid = parseDid;
 exports.pollUntil = pollUntil;

package/dist/index.mjs

@@ -554,6 +554,40 @@ var CliLoginSessionStates = {
 
 // src/types/agent.ts
 var AGENT_TAG_REGEX = /^[a-z0-9][a-z0-9_-]{0,38}[a-z0-9]$|^[a-z0-9]$/;
+var AGENT_NAME_REGEX = /^[a-z0-9_]{3,32}$/;
+function normalizeName(input) {
+  return input.trim().replace(/^@+/, "").trim().toLowerCase();
+}
+var RESERVED_NAMES = [
+  "admin",
+  "administrator",
+  "system",
+  "root",
+  "owner",
+  "operator",
+  "did",
+  "arp",
+  "heyarp",
+  "heyanon",
+  "anon",
+  "self",
+  "you",
+  "null",
+  "undefined",
+  "none",
+  "api",
+  "www",
+  "support",
+  "help",
+  "info"
+];
+var RESERVED_NAME_SET = new Set(RESERVED_NAMES);
+function isReservedName(name) {
+  return RESERVED_NAME_SET.has(normalizeName(name));
+}
+function isValidAgentName(name) {
+  return AGENT_NAME_REGEX.test(normalizeName(name));
+}
 
 // src/assets.ts
 var SOLANA_CLUSTER_IDS = {
@@ -939,4 +973,4 @@ var CliAuthTokenErrorCodes = {
   REQUIRED: "AUTH_TOKEN_REQUIRED"
 };
 
-export { AGENT_TAG_REGEX, ASSET_DECIMALS_MAX, ASSET_DECIMALS_MIN, ASSET_SYMBOL_MAX_LEN, ASSET_SYMBOL_MIN_LEN, ASSET_WHITELIST, ASSOCIATED_TOKEN_PROGRAM_ID_BASE58, BODY_TYPES, BodyTypes, CAIP19_REGEX, CLI_AUTH_TOKEN_ERROR_CODES, CLI_LOGIN_SESSION_STATES, CLI_LOGIN_SESSION_STORED_STATES, CREATE_LOCK_DISCRIMINATOR, CREATE_LOCK_NATIVE_DISCRIMINATOR, CURRENT_PROTOCOL_VERSION, CliAuthTokenErrorCodes, CliLoginSessionStates, DECIMAL_AMOUNT_REGEX, DECLINE_REASONS, DELEGATION_ACTIONS, DELEGATION_ACTIVE_STATES, DELEGATION_OFFER_REJECTION_CODES, DELEGATION_STATES, DEVNET_MINTS, DID_ARP_REGEX, DISCOVERY_SORTS, DelegationActions, DelegationOfferRejectionCodes, DelegationStates, DiscoverySorts, ED25519_SIG_PREFIX, ESCROW_PDA_SEEDS, ESCROW_PROGRAM_ID_BASE58, ESCROW_RELEASE_METHODS, EscrowReleaseMethods, HANDSHAKE_DECISIONS, HandshakeDecisions, INBOX_BLOCK_SCOPES, InboxBlockScopes, LIVE_RELATIONSHIP_STATE_NAMES, LOCK_ACCOUNT_DISCRIMINATOR, LOCK_ACCOUNT_SIZE, LOCK_STATE_NAMES, LOCK_TERMINAL_STATES, LockStates, LockTerminalStates, MAINNET_MINTS, MAX_CLOCK_SKEW_SECONDS, MAX_ENVELOPE_TTL_SECONDS, NATIVE_SOL_MINT_BASE58, NO_ARG_LIFECYCLE_INSTRUCTIONS, OWNER_SIGNING_METHODS, POST_COMMIT_ERROR_CODES, POST_COMMIT_ERROR_CODE_PREFIXES, PROTOCOL_VERSIONS, Purpose, READ_MODEL_STATUSES, RECEIPT_VERDICTS, RELATIONSHIP_STATE_NAMES, ReadModelStatuses, ReceiptVerdicts, RelationshipStates, SCRYPT_PARAMS, SHA256_HEX_RE, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, SYSTEM_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, WORK_LOG_STATES, WorkLogStates, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildLifecycleIxData, buildResolveDisputeIxData, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, computeLockAccountDiscriminator, decodeLockAccount, delegationIdToBytes16, deriveDelegationConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findAssetByAssetId, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, instructionDiscriminator, isAssetIdentifier, isBodyType, isCliLoginSessionWireState, isDecimalAmountString, isDeclineReason, isDelegationAction, isDelegationState, isDiscoverySort, isEscrowReleaseMethod, isHandshakeDecision, isInboxBlockScope, isPostCommitErrorCode, isReadModelStatus, isReceiptVerdict, isRelationshipState, isSha256Hex, isValidDid, isWhitelistedAssetId, isWorkLogState, listWhitelistedAssets, parseCaip19SolanaAssetId, parseDid, pollUntil, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sign2 as sign, signChallenge, signEnvelope, signKeyLinkAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyChallenge, verifyEnvelope, verifyKeyLinkAttestation };
+export { AGENT_NAME_REGEX, AGENT_TAG_REGEX, ASSET_DECIMALS_MAX, ASSET_DECIMALS_MIN, ASSET_SYMBOL_MAX_LEN, ASSET_SYMBOL_MIN_LEN, ASSET_WHITELIST, ASSOCIATED_TOKEN_PROGRAM_ID_BASE58, BODY_TYPES, BodyTypes, CAIP19_REGEX, CLI_AUTH_TOKEN_ERROR_CODES, CLI_LOGIN_SESSION_STATES, CLI_LOGIN_SESSION_STORED_STATES, CREATE_LOCK_DISCRIMINATOR, CREATE_LOCK_NATIVE_DISCRIMINATOR, CURRENT_PROTOCOL_VERSION, CliAuthTokenErrorCodes, CliLoginSessionStates, DECIMAL_AMOUNT_REGEX, DECLINE_REASONS, DELEGATION_ACTIONS, DELEGATION_ACTIVE_STATES, DELEGATION_OFFER_REJECTION_CODES, DELEGATION_STATES, DEVNET_MINTS, DID_ARP_REGEX, DISCOVERY_SORTS, DelegationActions, DelegationOfferRejectionCodes, DelegationStates, DiscoverySorts, ED25519_SIG_PREFIX, ESCROW_PDA_SEEDS, ESCROW_PROGRAM_ID_BASE58, ESCROW_RELEASE_METHODS, EscrowReleaseMethods, HANDSHAKE_DECISIONS, HandshakeDecisions, INBOX_BLOCK_SCOPES, InboxBlockScopes, LIVE_RELATIONSHIP_STATE_NAMES, LOCK_ACCOUNT_DISCRIMINATOR, LOCK_ACCOUNT_SIZE, LOCK_STATE_NAMES, LOCK_TERMINAL_STATES, LockStates, LockTerminalStates, MAINNET_MINTS, MAX_CLOCK_SKEW_SECONDS, MAX_ENVELOPE_TTL_SECONDS, NATIVE_SOL_MINT_BASE58, NO_ARG_LIFECYCLE_INSTRUCTIONS, OWNER_SIGNING_METHODS, POST_COMMIT_ERROR_CODES, POST_COMMIT_ERROR_CODE_PREFIXES, PROTOCOL_VERSIONS, Purpose, READ_MODEL_STATUSES, RECEIPT_VERDICTS, RELATIONSHIP_STATE_NAMES, RESERVED_NAMES, ReadModelStatuses, ReceiptVerdicts, RelationshipStates, SCRYPT_PARAMS, SHA256_HEX_RE, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, SYSTEM_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, WORK_LOG_STATES, WorkLogStates, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildLifecycleIxData, buildResolveDisputeIxData, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, computeLockAccountDiscriminator, decodeLockAccount, delegationIdToBytes16, deriveDelegationConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findAssetByAssetId, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, instructionDiscriminator, isAssetIdentifier, isBodyType, isCliLoginSessionWireState, isDecimalAmountString, isDeclineReason, isDelegationAction, isDelegationState, isDiscoverySort, isEscrowReleaseMethod, isHandshakeDecision, isInboxBlockScope, isPostCommitErrorCode, isReadModelStatus, isReceiptVerdict, isRelationshipState, isReservedName, isSha256Hex, isValidAgentName, isValidDid, isWhitelistedAssetId, isWorkLogState, listWhitelistedAssets, normalizeName, parseCaip19SolanaAssetId, parseDid, pollUntil, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sign2 as sign, signChallenge, signEnvelope, signKeyLinkAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyChallenge, verifyEnvelope, verifyKeyLinkAttestation };

package/dist/types/agent.d.ts

@@ -79,7 +79,14 @@ export interface AgentPublic {
     settlementPublicKey: string;
     /** attestationId of the live KEY-LINK row. */
     currentAttestationId: string;
-    name?: string;
+    /**
+     * Unique, immutable, human-readable handle (the agent's "username").
+     * Lowercase `^[a-z0-9_]{3,32}$` ({@link AGENT_NAME_REGEX}). Set once at
+     * registration and globally unique, so it resolves 1:1 to the DID and
+     * can be used to address the agent instead of its DID. Trust still binds
+     * to the DID — the name is convenience.
+     */
+    name: string;
     description?: string;
     /** Capability tags — always present (empty array when none). */
     tags: string[];
@@ -93,9 +100,10 @@ export interface AgentPublic {
  * Partial profile-update body for `PATCH /v1/agents/:did`. Omitted
  * fields stay as-is; `tags` present REPLACES the whole list (send `[]`
  * to clear); `acceptPrefs` present REPLACES the object (`null` clears).
+ * `name` is intentionally NOT here — the agent name is immutable (set
+ * once at registration, like the DID).
  */
 export interface UpdateAgentBody {
-    name?: string;
     description?: string;
     tags?: string[];
     acceptPrefs?: AcceptPrefs | null;
@@ -143,6 +151,38 @@ export interface AgentReputation {
  * before). The catalog filters on the persisted set.
  */
 export declare const AGENT_TAG_REGEX: RegExp;
+/**
+ * Agent NAME charset — the unique, immutable handle ("username") used to
+ * address an agent in place of its DID. Stricter than {@link AGENT_TAG_REGEX}:
+ * lowercase alphanumeric + underscore only (no dash), 3–32 chars. Single
+ * source of truth for the server `@Matches` + the CLI name→DID resolver.
+ * Inputs are canonicalized with {@link normalizeName} before this test.
+ */
+export declare const AGENT_NAME_REGEX: RegExp;
+/**
+ * Canonicalize a user-supplied name to its stored / looked-up form: trim,
+ * drop a leading `@` (the `@` convention isn't used, but tolerate it if a
+ * user types it out of habit), then lowercase. The result is what gets
+ * uniqueness-checked, persisted, and resolved.
+ */
+export declare function normalizeName(input: string): string;
+/**
+ * Reserved names that may NOT be registered — protocol / role words whose
+ * use as a handle would be confusing or impersonation-prone. Checked
+ * (against the normalized form) at registration. Single source of truth for
+ * the server's reserved-name gate. Every entry is itself a structurally
+ * valid name, so the gate is actually reachable.
+ */
+export declare const RESERVED_NAMES: readonly ["admin", "administrator", "system", "root", "owner", "operator", "did", "arp", "heyarp", "heyanon", "anon", "self", "you", "null", "undefined", "none", "api", "www", "support", "help", "info"];
+/** True if `name` (after {@link normalizeName}) is in {@link RESERVED_NAMES}. */
+export declare function isReservedName(name: string): boolean;
+/**
+ * Structural-validity guard for an agent name: tests the NORMALIZED form
+ * against {@link AGENT_NAME_REGEX} (so `Alice` / `@alice` pass — they
+ * normalize to `alice`). Does NOT check reserved-ness or uniqueness; those
+ * are {@link isReservedName} and the server's unique index.
+ */
+export declare function isValidAgentName(name: string): boolean;
 /** Response for `POST /v1/agents/challenge` (server DTO `IssueChallengeResponseDto`). */
 export interface ChallengeResponse {
     /** UUID — opaque handle passed back in challenge-response + register. */
@@ -170,7 +210,13 @@ export interface RegisterAgentRequest {
     };
     scryptKeyB64: string;
     scryptSaltB64: string;
-    name?: string;
+    /**
+     * Unique, immutable handle — lowercase `^[a-z0-9_]{3,32}$`
+     * ({@link AGENT_NAME_REGEX}), REQUIRED. The server normalizes it and
+     * rejects taken (`AGENT_NAME_TAKEN`) or reserved (`AGENT_NAME_RESERVED`)
+     * names at registration.
+     */
+    name: string;
     description?: string;
     /** Capability tags — lowercase alphanumeric + dash/underscore, max 20. */
     tags?: string[];

package/dist/types/discovery.d.ts

@@ -66,7 +66,8 @@ export interface DiscoveryLiveness {
 export interface DiscoveryResult {
     id: string;
     did: string;
-    name?: string;
+    /** Unique immutable handle — always present (every agent has one). */
+    name: string;
     description?: string;
     tags: string[];
     acceptPrefs?: AcceptPrefs;
@@ -98,7 +99,8 @@ export interface DiscoverySearchResponse {
  */
 export interface DiscoveryProfile {
     did: string;
-    name?: string;
+    /** Unique immutable handle — always present (every agent has one). */
+    name: string;
     description?: string;
     tags: string[];
     acceptPrefs?: AcceptPrefs;

package/dist/types/index.d.ts

@@ -18,6 +18,6 @@ export type { CliSessionCreated, CliTokenIssued, CliWhoami, MyAgentSummary, CliL
 export { CLI_LOGIN_SESSION_STORED_STATES, CLI_LOGIN_SESSION_STATES, CliLoginSessionStates, isCliLoginSessionWireState } from './cli-auth';
 export type { AssetIdentifierWire, DelegationPublic, ReceiptPublic, RelationshipPublic, WorkLogPublic, EventPublic, IngestResult, SenderSequenceResponse, InboxUnblockResult, ListRelationshipsQuery, ListInboxQuery, ListEventsQuery, ListDelegationsQuery, ListWorkLogsQuery, ListReceiptsQuery, } from './read-model';
 export type { AcceptPrefs, AcceptCurrency, AgentRegisteredResponse, AgentPublic, UpdateAgentBody, RegisterAgentRequest, ChallengeResponse, ReputationScores, ReputationCounters, AgentReputation, } from './agent';
-export { AGENT_TAG_REGEX } from './agent';
+export { AGENT_TAG_REGEX, AGENT_NAME_REGEX, RESERVED_NAMES, isReservedName, isValidAgentName, normalizeName } from './agent';
 export type { OwnerSigningMethod, KeyLinkPayload, ScryptPasswordAttestation } from './identity';
 export { SCRYPT_PARAMS, OWNER_SIGNING_METHODS } from './identity';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/sdk",
-  "version": "0.0.26",
+  "version": "0.0.29",
   "description": "TypeScript SDK for the Agent Relationship Protocol — canonical JSON, Ed25519 envelope sign/verify, did:arp identity, scrypt key attestation, chain-audit helpers.",
   "license": "MIT",
   "keywords": [