evolcore 0.0.1 → 0.0.2

package/dist/config/contact-book.js

@@ -0,0 +1,371 @@
+import { agentContactConfig } from '../paths.js';
+import { isValidAid } from '../aun/aid/validation.js';
+import { ConfigTarget, read, validateConfig, write } from './config-manager.js';
+export class ContactBookError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ContactBookError';
+    }
+}
+let aliasMapCache = new WeakMap();
+const emptyAliasMap = {
+    scopedAliasToPrimary: new Map(),
+    conflictingScopedAliases: new Set(),
+    legacyAliasToPrimary: new Map(),
+    conflictingLegacyAliases: new Set(),
+};
+const SCOPED_ALIAS_PREFIX = 'channel-key:';
+export function agentContactConfigPath(aid) {
+    return agentContactConfig(aid);
+}
+export function readContactBook(selfAid, opts = {}) {
+    if (!selfAid)
+        return null;
+    return read(ConfigTarget.Contact, { self: selfAid }, { cache: opts.cache ?? true });
+}
+export function resolvePrincipal(selfAid, channelType, actorId, channelKey) {
+    const normalizedActor = String(actorId || '').trim();
+    const normalizedChannel = String(channelType || '').trim().toLowerCase();
+    if (normalizedChannel === 'aun') {
+        return isValidAid(normalizedActor)
+            ? { principalId: normalizedActor, principalStatus: 'native_aid' }
+            : { principalStatus: normalizedActor ? 'unmapped' : 'error' };
+    }
+    const normalizedSelf = String(selfAid || '').trim();
+    const normalizedChannelKey = normalizeChannelKey(normalizedSelf, normalizedChannel, channelKey);
+    const legacyAlias = normalizeLegacyAlias(normalizedChannel, normalizedActor);
+    if (!isValidAid(normalizedSelf) || !normalizedChannelKey || !legacyAlias) {
+        return { principalStatus: 'error' };
+    }
+    const scopedAlias = scopedAliasLookupKey(normalizedChannelKey, normalizedActor);
+    try {
+        const aliases = loadAliasMap(normalizedSelf);
+        if (aliases.conflictingScopedAliases.has(scopedAlias)) {
+            return { principalStatus: 'conflict' };
+        }
+        const scopedPrincipalId = aliases.scopedAliasToPrimary.get(scopedAlias);
+        if (scopedPrincipalId) {
+            return { principalId: scopedPrincipalId, principalStatus: 'mapped' };
+        }
+        // Legacy aliases did not identify a channel instance. They remain trusted only
+        // while the configured channel type has exactly one matching instance.
+        if (!isUnambiguousLegacyChannel(normalizedSelf, normalizedChannel, normalizedChannelKey)) {
+            return { principalStatus: 'unmapped' };
+        }
+        if (aliases.conflictingLegacyAliases.has(legacyAlias)) {
+            return { principalStatus: 'conflict' };
+        }
+        const legacyPrincipalId = aliases.legacyAliasToPrimary.get(legacyAlias);
+        return legacyPrincipalId
+            ? { principalId: legacyPrincipalId, principalStatus: 'mapped' }
+            : { principalStatus: 'unmapped' };
+    }
+    catch {
+        return { principalStatus: 'error' };
+    }
+}
+export function resolvePrimaryId(selfAid, channelType, actorId, channelKey) {
+    const normalizedActor = String(actorId || '').trim();
+    return resolvePrincipal(selfAid, channelType, normalizedActor, channelKey).principalId ?? normalizedActor;
+}
+export function bindContactAlias(selfAid, primaryId, channelType, actorId, channelKey) {
+    const primary = normalizePrimaryId(primaryId);
+    const alias = requireScopedAlias(selfAid, channelType, actorId, channelKey);
+    const legacyAlias = requireLegacyAlias(channelType, actorId);
+    ensureNativeAidIsNotRemapped(primary, channelType, actorId);
+    const next = cloneContactBook(readContactBook(selfAid, { cache: true }));
+    ensureScopedAliasAvailable(next, selfAid, primary, alias.lookupKey);
+    const contacts = next.contacts ?? {};
+    let removedLegacyAlias = false;
+    // An explicit scoped bind supersedes every unscoped copy of the same alias.
+    // Otherwise unbinding the scoped entry could silently reactivate a legacy
+    // mapping owned by another principal.
+    for (const [contactId, value] of Object.entries(contacts)) {
+        const entry = normalizeContactEntry(value);
+        const filtered = entry.aliases.filter(item => normalizeLegacyAliasString(item) !== legacyAlias);
+        if (filtered.length !== entry.aliases.length) {
+            contacts[contactId] = { ...entry, aliases: filtered };
+            removedLegacyAlias = true;
+        }
+    }
+    const current = normalizeContactEntry(contacts[primary]);
+    const alreadyScoped = current.aliases.some(value => (normalizeScopedAliasString(value, selfAid)?.lookupKey === alias.lookupKey));
+    if (alreadyScoped && !removedLegacyAlias) {
+        return false;
+    }
+    contacts[primary] = {
+        ...current,
+        aliases: alreadyScoped
+            ? current.aliases
+            : [...current.aliases, alias.serialized],
+    };
+    next.contacts = contacts;
+    write(ConfigTarget.Contact, next, { self: selfAid });
+    return true;
+}
+export function unbindContactAlias(selfAid, primaryId, channelType, actorId, channelKey) {
+    const primary = normalizePrimaryId(primaryId);
+    const alias = requireScopedAlias(selfAid, channelType, actorId, channelKey);
+    const legacyAlias = requireLegacyAlias(channelType, actorId);
+    const next = cloneContactBook(readContactBook(selfAid, { cache: true }));
+    const contacts = next.contacts ?? {};
+    let changed = false;
+    // Remove the requested scoped binding from the target principal and purge
+    // every unscoped copy of the same raw alias.  Legacy aliases do not carry a
+    // channel-instance identity, so retaining one on another contact would
+    // silently reactivate that principal after this scoped binding is revoked.
+    for (const [contactId, value] of Object.entries(contacts)) {
+        const entry = normalizeContactEntry(value);
+        const filtered = entry.aliases.filter(item => {
+            const isTargetScoped = contactId.trim() === primary
+                && normalizeScopedAliasString(item, selfAid)?.lookupKey === alias.lookupKey;
+            const isLegacyCopy = normalizeLegacyAliasString(item) === legacyAlias;
+            return !isTargetScoped && !isLegacyCopy;
+        });
+        if (filtered.length !== entry.aliases.length) {
+            contacts[contactId] = { ...entry, aliases: filtered };
+            changed = true;
+        }
+    }
+    if (!changed) {
+        return false;
+    }
+    next.contacts = contacts;
+    write(ConfigTarget.Contact, next, { self: selfAid });
+    return true;
+}
+export function clearContactBookCache() {
+    aliasMapCache = new WeakMap();
+}
+function loadAliasMap(selfAid) {
+    const book = readContactBook(selfAid, { cache: true });
+    if (!book)
+        return emptyAliasMap;
+    const cached = aliasMapCache.get(book);
+    if (cached)
+        return cached;
+    const validationErrors = validateConfig(ConfigTarget.Contact, book);
+    if (validationErrors.length > 0) {
+        throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact book for ${selfAid}: ${validationErrors.join('; ')}`);
+    }
+    const built = buildAliasMap(book, selfAid);
+    aliasMapCache.set(book, built);
+    return built;
+}
+function buildAliasMap(config, selfAid) {
+    const scopedAliasToPrimary = new Map();
+    const conflictingScopedAliases = new Set();
+    const legacyAliasToPrimary = new Map();
+    const conflictingLegacyAliases = new Set();
+    const contacts = config?.contacts;
+    if (!contacts || typeof contacts !== 'object' || Array.isArray(contacts)) {
+        return {
+            scopedAliasToPrimary,
+            conflictingScopedAliases,
+            legacyAliasToPrimary,
+            conflictingLegacyAliases,
+        };
+    }
+    for (const [rawPrimaryId, entry] of Object.entries(contacts)) {
+        const primaryId = rawPrimaryId.trim();
+        if (!isValidAid(primaryId) || !entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
+        for (const rawAlias of aliases) {
+            const scoped = normalizeScopedAliasString(rawAlias, selfAid);
+            if (scoped) {
+                addAliasMapping(scopedAliasToPrimary, conflictingScopedAliases, scoped.lookupKey, primaryId);
+            }
+            else {
+                const legacy = normalizeLegacyAliasString(rawAlias);
+                if (legacy) {
+                    addAliasMapping(legacyAliasToPrimary, conflictingLegacyAliases, legacy, primaryId);
+                }
+            }
+        }
+    }
+    return {
+        scopedAliasToPrimary,
+        conflictingScopedAliases,
+        legacyAliasToPrimary,
+        conflictingLegacyAliases,
+    };
+}
+function addAliasMapping(aliases, conflicts, alias, primaryId) {
+    if (conflicts.has(alias))
+        return;
+    const existing = aliases.get(alias);
+    if (existing && existing !== primaryId) {
+        aliases.delete(alias);
+        conflicts.add(alias);
+        return;
+    }
+    aliases.set(alias, primaryId);
+}
+function cloneContactBook(config) {
+    const next = config ? { ...config } : {};
+    const contacts = {};
+    const rawContacts = config?.contacts;
+    if (rawContacts && typeof rawContacts === 'object' && !Array.isArray(rawContacts)) {
+        for (const [primaryId, entry] of Object.entries(rawContacts)) {
+            contacts[primaryId] = normalizeContactEntry(entry);
+        }
+    }
+    next.contacts = contacts;
+    return next;
+}
+function normalizeContactEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { aliases: [] };
+    }
+    const entry = value;
+    return {
+        ...entry,
+        aliases: Array.isArray(entry.aliases)
+            ? entry.aliases.filter((item) => typeof item === 'string')
+            : [],
+    };
+}
+function ensureScopedAliasAvailable(config, selfAid, primaryId, alias) {
+    const owners = findScopedAliasOwners(config, selfAid, alias);
+    if (owners.size === 0)
+        return;
+    if (owners.size === 1 && owners.has(primaryId))
+        return;
+    throw new ContactBookError('ALIAS_CONFLICT', `Alias "${alias}" is already bound to ${[...owners].join(', ')}`);
+}
+function findScopedAliasOwners(config, selfAid, alias) {
+    const owners = new Set();
+    const contacts = config.contacts;
+    if (!contacts || typeof contacts !== 'object' || Array.isArray(contacts))
+        return owners;
+    for (const [rawPrimaryId, entry] of Object.entries(contacts)) {
+        const primaryId = rawPrimaryId.trim();
+        if (!primaryId || !entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
+        if (aliases.some(value => normalizeScopedAliasString(value, selfAid)?.lookupKey === alias)) {
+            owners.add(primaryId);
+        }
+    }
+    return owners;
+}
+function normalizePrimaryId(value) {
+    const primaryId = String(value || '').trim();
+    if (!isValidAid(primaryId)) {
+        throw new ContactBookError('INVALID_PRIMARY_ID', `Invalid contact primary AID: ${String(value)}`);
+    }
+    return primaryId;
+}
+function requireLegacyAlias(channelType, actorId) {
+    const alias = normalizeLegacyAlias(channelType, actorId);
+    if (!alias) {
+        throw new ContactBookError('INVALID_ALIAS', `Invalid contact alias: ${String(channelType)}:${String(actorId)}`);
+    }
+    return alias;
+}
+function normalizeLegacyAlias(channelType, actorId) {
+    const channel = String(channelType || '').trim().toLowerCase();
+    const id = String(actorId || '').trim();
+    if (!/^[a-z0-9_-]+$/.test(channel) || !id)
+        return null;
+    return `${channel}:${id}`;
+}
+function normalizeLegacyAliasString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.startsWith(SCOPED_ALIAS_PREFIX))
+        return null;
+    const idx = trimmed.indexOf(':');
+    if (idx <= 0 || idx === trimmed.length - 1)
+        return null;
+    return normalizeLegacyAlias(trimmed.slice(0, idx), trimmed.slice(idx + 1));
+}
+function requireScopedAlias(selfAid, channelType, actorId, channelKey) {
+    const normalizedActor = String(actorId || '').trim();
+    const normalizedChannel = String(channelType || '').trim().toLowerCase();
+    const normalizedChannelKey = normalizeChannelKey(selfAid, normalizedChannel, channelKey);
+    if (!normalizedActor || !normalizedChannelKey) {
+        throw new ContactBookError('INVALID_CHANNEL_ALIAS', `Invalid scoped contact alias: ${String(channelKey)}:${String(actorId)}`);
+    }
+    return {
+        lookupKey: scopedAliasLookupKey(normalizedChannelKey, normalizedActor),
+        serialized: serializeScopedAlias(normalizedChannelKey, normalizedActor),
+    };
+}
+function normalizeScopedAliasString(value, selfAid) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith(SCOPED_ALIAS_PREFIX))
+        return null;
+    const encoded = trimmed.slice(SCOPED_ALIAS_PREFIX.length);
+    const separator = encoded.indexOf(':');
+    if (separator <= 0 || separator === encoded.length - 1)
+        return null;
+    try {
+        const channelKey = decodeURIComponent(encoded.slice(0, separator));
+        const actorId = decodeURIComponent(encoded.slice(separator + 1)).trim();
+        const channelType = channelKey.split('#', 1)[0]?.toLowerCase() ?? '';
+        const normalizedChannelKey = normalizeChannelKey(selfAid, channelType, channelKey);
+        if (!normalizedChannelKey || !actorId)
+            return null;
+        return {
+            lookupKey: scopedAliasLookupKey(normalizedChannelKey, actorId),
+            serialized: serializeScopedAlias(normalizedChannelKey, actorId),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function serializeScopedAlias(channelKey, actorId) {
+    return `${SCOPED_ALIAS_PREFIX}${encodeURIComponent(channelKey)}:${encodeURIComponent(actorId)}`;
+}
+function scopedAliasLookupKey(channelKey, actorId) {
+    return JSON.stringify([channelKey, actorId]);
+}
+function normalizeChannelKey(selfAid, channelType, value) {
+    const key = typeof value === 'string' ? value.trim() : '';
+    const parts = key.split('#');
+    if (parts.length !== 3)
+        return null;
+    const [rawType, keySelfAid, name] = parts;
+    const normalizedType = rawType.toLowerCase();
+    if (!/^[a-z0-9_-]+$/.test(normalizedType)
+        || normalizedType !== channelType
+        || keySelfAid !== selfAid
+        || !name) {
+        return null;
+    }
+    return `${normalizedType}#${keySelfAid}#${name}`;
+}
+function isUnambiguousLegacyChannel(selfAid, channelType, channelKey) {
+    try {
+        const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
+        const matches = new Set();
+        for (const candidate of agent?.channels ?? []) {
+            if (!candidate || typeof candidate !== 'object')
+                continue;
+            const candidateType = String(candidate.type || '').trim().toLowerCase();
+            const candidateName = String(candidate.name || '').trim();
+            if (candidateType !== channelType || !candidateName || candidateName.includes('#'))
+                continue;
+            matches.add(`${candidateType}#${selfAid}#${candidateName}`);
+        }
+        return matches.size === 1 && matches.has(channelKey);
+    }
+    catch {
+        return false;
+    }
+}
+function ensureNativeAidIsNotRemapped(primaryId, channelType, actorId) {
+    const channel = String(channelType || '').trim().toLowerCase();
+    const actor = String(actorId || '').trim();
+    if (channel === 'aun' && isValidAid(actor) && actor !== primaryId) {
+        throw new ContactBookError('NATIVE_AID_REMAP_FORBIDDEN', `Native AID "${actor}" cannot be remapped to "${primaryId}"`);
+    }
+}