@aster-rpc/aster 0.1.2

package/dist/peer-store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * aster/peer-store -- Per-peer admission attribute store.
+ *
+ * Bridges the gap between admission (where attributes are determined)
+ * and RPC dispatch (where attributes are needed for authorization).
+ *
+ * Expiry: each admission records the credential's `expiresAt` (epoch
+ * seconds). Lookups check expiry and lazily evict stale entries. A
+ * background reaper sweeps entries that are never looked up again.
+ *
+ * Config: ASTER_PEER_TTL_S env var (default 86400 = 24h) sets the
+ * server-side upper bound on how long a peer stays admitted.
+ */
+/** Server-side upper bound on peer admission lifetime (seconds). */
+export declare const PEER_TTL_S: number;
+/** Record of a successful peer admission. */
+export interface PeerAdmission {
+    endpointId: string;
+    handle: string;
+    attributes: Map<string, string>;
+    admittedAt: number;
+    expiresAt: number;
+    /** "consumer_admission" | "aster.admission" */
+    admissionPath: string;
+}
+/** Create a PeerAdmission with defaults for optional fields. */
+export declare function createPeerAdmission(opts: Pick<PeerAdmission, 'endpointId'> & Partial<Omit<PeerAdmission, 'endpointId'>>): PeerAdmission;
+/**
+ * In-memory store mapping peer endpointId to admission attributes.
+ *
+ * Entries are lazily evicted on access when expired. Call startReaper()
+ * to enable periodic sweeps of entries that are never accessed.
+ */
+export declare class PeerAttributeStore {
+    private peers;
+    private reaperTimer;
+    /** Record a successful admission. */
+    admit(admission: PeerAdmission): void;
+    /** Look up admission record for a peer. Returns undefined if expired. */
+    get(endpointId: string): PeerAdmission | undefined;
+    /** Remove a peer on disconnect or revocation. */
+    remove(endpointId: string): void;
+    /** Get attributes map for a peer, or empty map if expired/not admitted. */
+    getAttributes(endpointId: string): Map<string, string>;
+    /** Remove all expired entries. Returns count removed. */
+    sweepExpired(): number;
+    get peerCount(): number;
+    /** Start background reaper (call once at server start). */
+    startReaper(): void;
+    /** Stop background reaper. */
+    stopReaper(): void;
+}
+//# sourceMappingURL=peer-store.d.ts.map

package/dist/peer-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-store.d.ts","sourceRoot":"","sources":["../src/peer-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oEAAoE;AACpE,eAAO,MAAM,UAAU,EAAE,MAKrB,CAAC;AAIL,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,GACnF,aAAa,CASf;AASD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,WAAW,CAA+C;IAElE,qCAAqC;IACrC,KAAK,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAIrC,yEAAyE;IACzE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAUlD,iDAAiD;IACjD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIhC,2EAA2E;IAC3E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAKtD,yDAAyD;IACzD,YAAY,IAAI,MAAM;IAWtB,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,2DAA2D;IAC3D,WAAW,IAAI,IAAI;IAQnB,8BAA8B;IAC9B,UAAU,IAAI,IAAI;CAMnB"}

package/dist/peer-store.js

@@ -0,0 +1,105 @@
+/**
+ * aster/peer-store -- Per-peer admission attribute store.
+ *
+ * Bridges the gap between admission (where attributes are determined)
+ * and RPC dispatch (where attributes are needed for authorization).
+ *
+ * Expiry: each admission records the credential's `expiresAt` (epoch
+ * seconds). Lookups check expiry and lazily evict stale entries. A
+ * background reaper sweeps entries that are never looked up again.
+ *
+ * Config: ASTER_PEER_TTL_S env var (default 86400 = 24h) sets the
+ * server-side upper bound on how long a peer stays admitted.
+ */
+/** Server-side upper bound on peer admission lifetime (seconds). */
+export const PEER_TTL_S = (() => {
+    if (typeof process !== 'undefined' && process.env?.ASTER_PEER_TTL_S) {
+        return parseFloat(process.env.ASTER_PEER_TTL_S);
+    }
+    return 86400;
+})();
+const _REAPER_INTERVAL_MS = 300_000;
+/** Create a PeerAdmission with defaults for optional fields. */
+export function createPeerAdmission(opts) {
+    return {
+        endpointId: opts.endpointId,
+        handle: opts.handle ?? '',
+        attributes: opts.attributes ?? new Map(),
+        admittedAt: opts.admittedAt ?? Date.now() / 1000,
+        expiresAt: opts.expiresAt ?? 0,
+        admissionPath: opts.admissionPath ?? '',
+    };
+}
+function isExpired(admission) {
+    const now = Date.now() / 1000;
+    if (admission.expiresAt > 0 && now > admission.expiresAt)
+        return true;
+    if (now > admission.admittedAt + PEER_TTL_S)
+        return true;
+    return false;
+}
+/**
+ * In-memory store mapping peer endpointId to admission attributes.
+ *
+ * Entries are lazily evicted on access when expired. Call startReaper()
+ * to enable periodic sweeps of entries that are never accessed.
+ */
+export class PeerAttributeStore {
+    peers = new Map();
+    reaperTimer = null;
+    /** Record a successful admission. */
+    admit(admission) {
+        this.peers.set(admission.endpointId, admission);
+    }
+    /** Look up admission record for a peer. Returns undefined if expired. */
+    get(endpointId) {
+        const admission = this.peers.get(endpointId);
+        if (!admission)
+            return undefined;
+        if (isExpired(admission)) {
+            this.peers.delete(endpointId);
+            return undefined;
+        }
+        return admission;
+    }
+    /** Remove a peer on disconnect or revocation. */
+    remove(endpointId) {
+        this.peers.delete(endpointId);
+    }
+    /** Get attributes map for a peer, or empty map if expired/not admitted. */
+    getAttributes(endpointId) {
+        const admission = this.get(endpointId);
+        return admission ? new Map(admission.attributes) : new Map();
+    }
+    /** Remove all expired entries. Returns count removed. */
+    sweepExpired() {
+        let count = 0;
+        for (const [eid, adm] of this.peers) {
+            if (isExpired(adm)) {
+                this.peers.delete(eid);
+                count++;
+            }
+        }
+        return count;
+    }
+    get peerCount() {
+        return this.peers.size;
+    }
+    /** Start background reaper (call once at server start). */
+    startReaper() {
+        if (this.reaperTimer != null)
+            return;
+        this.reaperTimer = setInterval(() => this.sweepExpired(), _REAPER_INTERVAL_MS);
+        if (typeof this.reaperTimer === 'object' && 'unref' in this.reaperTimer) {
+            this.reaperTimer.unref();
+        }
+    }
+    /** Stop background reaper. */
+    stopReaper() {
+        if (this.reaperTimer != null) {
+            clearInterval(this.reaperTimer);
+            this.reaperTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=peer-store.js.map

package/dist/peer-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-store.js","sourceRoot":"","sources":["../src/peer-store.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Wire-protocol types.
+ *
+ * Spec reference: S6.2 (StreamHeader), S6.4 (RpcStatus/trailer)
+ *
+ * These types are always serialized with Fory XLANG, regardless of the
+ * service's negotiated serialization mode.
+ */
+/** First frame on every QUIC stream (HEADER flag). */
+export declare class StreamHeader {
+    /** Wire type tag for Fory XLANG registration. */
+    static readonly wireType = "_aster/StreamHeader";
+    service: string;
+    method: string;
+    version: number;
+    callId: string;
+    deadlineEpochMs: number;
+    serializationMode: number;
+    metadataKeys: string[];
+    metadataValues: string[];
+    constructor(init?: Partial<StreamHeader>);
+}
+/** Per-call header within a session stream (CALL flag). */
+export declare class CallHeader {
+    static readonly wireType = "_aster/CallHeader";
+    method: string;
+    callId: string;
+    deadlineEpochMs: number;
+    metadataKeys: string[];
+    metadataValues: string[];
+    constructor(init?: Partial<CallHeader>);
+}
+/** Trailing status frame (TRAILER flag). */
+export declare class RpcStatus {
+    static readonly wireType = "_aster/RpcStatus";
+    code: number;
+    message: string;
+    detailKeys: string[];
+    detailValues: string[];
+    constructor(init?: Partial<RpcStatus>);
+    /** Convert detail arrays to a key-value record. */
+    get details(): Record<string, string>;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sDAAsD;AACtD,qBAAa,YAAY;IACvB,iDAAiD;IACjD,MAAM,CAAC,QAAQ,CAAC,QAAQ,yBAAyB;IAEjD,OAAO,SAAM;IACb,MAAM,SAAM;IACZ,OAAO,SAAK;IACZ,MAAM,SAAM;IACZ,eAAe,SAAK;IACpB,iBAAiB,SAAK;IACtB,YAAY,EAAE,MAAM,EAAE,CAAM;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAM;gBAElB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;CAGzC;AAED,2DAA2D;AAC3D,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,QAAQ,uBAAuB;IAE/C,MAAM,SAAM;IACZ,MAAM,SAAM;IACZ,eAAe,SAAK;IACpB,YAAY,EAAE,MAAM,EAAE,CAAM;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAM;gBAElB,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC;CAGvC;AAED,4CAA4C;AAC5C,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,QAAQ,sBAAsB;IAE9C,IAAI,SAAK;IACT,OAAO,SAAM;IACb,UAAU,EAAE,MAAM,EAAE,CAAM;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAM;gBAEhB,IAAI,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC;IAIrC,mDAAmD;IACnD,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMpC;CACF"}

package/dist/protocol.js

@@ -0,0 +1,59 @@
+/**
+ * Wire-protocol types.
+ *
+ * Spec reference: S6.2 (StreamHeader), S6.4 (RpcStatus/trailer)
+ *
+ * These types are always serialized with Fory XLANG, regardless of the
+ * service's negotiated serialization mode.
+ */
+/** First frame on every QUIC stream (HEADER flag). */
+export class StreamHeader {
+    /** Wire type tag for Fory XLANG registration. */
+    static wireType = '_aster/StreamHeader';
+    service = '';
+    method = '';
+    version = 0;
+    callId = '';
+    deadlineEpochMs = 0;
+    serializationMode = 0;
+    metadataKeys = [];
+    metadataValues = [];
+    constructor(init) {
+        if (init)
+            Object.assign(this, init);
+    }
+}
+/** Per-call header within a session stream (CALL flag). */
+export class CallHeader {
+    static wireType = '_aster/CallHeader';
+    method = '';
+    callId = '';
+    deadlineEpochMs = 0;
+    metadataKeys = [];
+    metadataValues = [];
+    constructor(init) {
+        if (init)
+            Object.assign(this, init);
+    }
+}
+/** Trailing status frame (TRAILER flag). */
+export class RpcStatus {
+    static wireType = '_aster/RpcStatus';
+    code = 0;
+    message = '';
+    detailKeys = [];
+    detailValues = [];
+    constructor(init) {
+        if (init)
+            Object.assign(this, init);
+    }
+    /** Convert detail arrays to a key-value record. */
+    get details() {
+        const result = {};
+        for (let i = 0; i < this.detailKeys.length; i++) {
+            result[this.detailKeys[i]] = this.detailValues[i] ?? '';
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sDAAsD;AACtD,MAAM,OAAO,YAAY;IACvB,iDAAiD;IACjD,MAAM,CAAU,QAAQ,GAAG,qBAAqB,CAAC;IAEjD,OAAO,GAAG,EAAE,CAAC;IACb,MAAM,GAAG,EAAE,CAAC;IACZ,OAAO,GAAG,CAAC,CAAC;IACZ,MAAM,GAAG,EAAE,CAAC;IACZ,eAAe,GAAG,CAAC,CAAC;IACpB,iBAAiB,GAAG,CAAC,CAAC;IACtB,YAAY,GAAa,EAAE,CAAC;IAC5B,cAAc,GAAa,EAAE,CAAC;IAE9B,YAAY,IAA4B;QACtC,IAAI,IAAI;YAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;;AAGH,2DAA2D;AAC3D,MAAM,OAAO,UAAU;IACrB,MAAM,CAAU,QAAQ,GAAG,mBAAmB,CAAC;IAE/C,MAAM,GAAG,EAAE,CAAC;IACZ,MAAM,GAAG,EAAE,CAAC;IACZ,eAAe,GAAG,CAAC,CAAC;IACpB,YAAY,GAAa,EAAE,CAAC;IAC5B,cAAc,GAAa,EAAE,CAAC;IAE9B,YAAY,IAA0B;QACpC,IAAI,IAAI;YAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;;AAGH,4CAA4C;AAC5C,MAAM,OAAO,SAAS;IACpB,MAAM,CAAU,QAAQ,GAAG,kBAAkB,CAAC;IAE9C,IAAI,GAAG,CAAC,CAAC;IACT,OAAO,GAAG,EAAE,CAAC;IACb,UAAU,GAAa,EAAE,CAAC;IAC1B,YAAY,GAAa,EAAE,CAAC;IAE5B,YAAY,IAAyB;QACnC,IAAI,IAAI;YAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,mDAAmD;IACnD,IAAI,OAAO;QACT,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC"}

package/dist/registration.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @aster endpoint registration loop.
+ *
+ * Background task that registers producer endpoints with the @aster
+ * service so consumers can discover them. Mirrors the Python
+ * `_aster_registration_loop` / `_register_endpoints_with_aster` /
+ * `_resolve_aster_address` / `_load_producer_tokens` from runtime.py.
+ *
+ * Usage:
+ *   const tokens = loadProducerTokens(identityData);
+ *   const abort = startRegistrationLoop({ tokens, nodeInfo, logger });
+ *   // later...
+ *   abort.abort();
+ */
+import type { AsterLogger } from './logging.js';
+/** Token data for a single published service (from .aster-identity). */
+export interface ProducerTokenEntry {
+    producer_token: string;
+    [key: string]: unknown;
+}
+/** Node addressing information passed to the registration RPC. */
+export interface NodeInfo {
+    nodeId: string;
+    relay: string;
+    directAddrs: string[];
+}
+/** Options for `startRegistrationLoop`. */
+export interface RegistrationLoopOptions {
+    /** Map of service name -> token data (from `loadProducerTokens`). */
+    tokens: Map<string, ProducerTokenEntry>;
+    /** This node's addressing info. */
+    nodeInfo: NodeInfo;
+    /** TTL in seconds for endpoint leases. Default: 300 (5 min). */
+    ttl?: number;
+    /** Logger instance. */
+    logger?: AsterLogger;
+    /** Optional identity peer entry for resolving @aster address. */
+    identityPeer?: Record<string, unknown>;
+    /**
+     * Factory that opens an IrohTransport to the given address.
+     * The caller provides this so the registration module stays decoupled
+     * from native addon loading.
+     */
+    connectTransport: (address: string) => Promise<RegistrationTransport>;
+}
+/** Minimal transport interface -- only unary is needed for registration. */
+export interface RegistrationTransport {
+    unary(service: string, method: string, payload: unknown): Promise<unknown>;
+    close(): Promise<void>;
+}
+/**
+ * Extract producer service tokens from parsed identity data.
+ *
+ * In the .aster-identity TOML file, published services live under
+ * `[published_services.<ServiceName>]` sections. The identity loader
+ * returns the peer entry as a plain object; this function pulls out
+ * entries that have a `producer_token` field.
+ *
+ * @param identityData - The peer entry object from the identity loader.
+ * @returns Map of service name to token data.
+ */
+export declare function loadProducerTokens(identityData: Record<string, unknown> | null | undefined): Map<string, ProducerTokenEntry>;
+/**
+ * Resolve the @aster service address for endpoint registration.
+ *
+ * Checks (in order):
+ * 1. `ASTER_SERVICE_ADDRESS` environment variable
+ * 2. `aster_service` field in the identity peer entry
+ * 3. Returns `null` if neither is set (DNS TXT lookup is future work)
+ */
+export declare function resolveAsterAddress(identityPeer?: Record<string, unknown> | null): string | null;
+/**
+ * Start the background registration loop.
+ *
+ * Registers endpoints with @aster immediately (after a 2 s startup
+ * delay), then re-registers at 75% of TTL to keep leases alive.
+ *
+ * Returns an `AbortController` -- call `.abort()` to stop the loop.
+ */
+export declare function startRegistrationLoop(opts: RegistrationLoopOptions): AbortController;
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACxC,mCAAmC;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACvE;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACvD,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAkBjC;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC5C,MAAM,GAAG,IAAI,CAcf;AA2DD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,uBAAuB,GAC5B,eAAe,CA2BjB"}

package/dist/registration.js

@@ -0,0 +1,161 @@
+/**
+ * @aster endpoint registration loop.
+ *
+ * Background task that registers producer endpoints with the @aster
+ * service so consumers can discover them. Mirrors the Python
+ * `_aster_registration_loop` / `_register_endpoints_with_aster` /
+ * `_resolve_aster_address` / `_load_producer_tokens` from runtime.py.
+ *
+ * Usage:
+ *   const tokens = loadProducerTokens(identityData);
+ *   const abort = startRegistrationLoop({ tokens, nodeInfo, logger });
+ *   // later...
+ *   abort.abort();
+ */
+// ── loadProducerTokens ───────────────────────────────────────────────────────
+/**
+ * Extract producer service tokens from parsed identity data.
+ *
+ * In the .aster-identity TOML file, published services live under
+ * `[published_services.<ServiceName>]` sections. The identity loader
+ * returns the peer entry as a plain object; this function pulls out
+ * entries that have a `producer_token` field.
+ *
+ * @param identityData - The peer entry object from the identity loader.
+ * @returns Map of service name to token data.
+ */
+export function loadProducerTokens(identityData) {
+    const tokens = new Map();
+    if (!identityData)
+        return tokens;
+    const published = identityData.published_services;
+    if (!published || typeof published !== 'object')
+        return tokens;
+    for (const [svcName, tokenData] of Object.entries(published)) {
+        if (tokenData &&
+            typeof tokenData === 'object' &&
+            tokenData.producer_token) {
+            tokens.set(svcName, tokenData);
+        }
+    }
+    return tokens;
+}
+// ── resolveAsterAddress ──────────────────────────────────────────────────────
+/**
+ * Resolve the @aster service address for endpoint registration.
+ *
+ * Checks (in order):
+ * 1. `ASTER_SERVICE_ADDRESS` environment variable
+ * 2. `aster_service` field in the identity peer entry
+ * 3. Returns `null` if neither is set (DNS TXT lookup is future work)
+ */
+export function resolveAsterAddress(identityPeer) {
+    // Env var override
+    const envAddr = typeof process !== 'undefined'
+        ? process.env.ASTER_SERVICE_ADDRESS ?? ''
+        : '';
+    if (envAddr)
+        return envAddr;
+    // Identity file -- the peer entry may have aster_service config
+    if (identityPeer) {
+        const addr = identityPeer.aster_service;
+        if (typeof addr === 'string' && addr)
+            return addr;
+    }
+    return null;
+}
+// ── registerEndpoints (one-shot) ─────────────────────────────────────────────
+/**
+ * One-shot registration of all published service endpoints with @aster.
+ *
+ * For each service with a producer token, calls
+ * `PublicationService.register_endpoint` on the @aster instance.
+ */
+async function registerEndpoints(opts, ttl) {
+    if (opts.tokens.size === 0)
+        return;
+    const asterAddr = resolveAsterAddress(opts.identityPeer);
+    if (!asterAddr) {
+        opts.logger?.debug('No @aster address configured -- skipping registration');
+        return;
+    }
+    let transport = null;
+    try {
+        transport = await opts.connectTransport(asterAddr);
+    }
+    catch (e) {
+        opts.logger?.debug(`Could not connect to @aster: ${e}`);
+        return;
+    }
+    try {
+        for (const [svcName, tokenData] of opts.tokens) {
+            try {
+                const request = {
+                    producer_token: JSON.stringify(tokenData),
+                    node_id: opts.nodeInfo.nodeId,
+                    relay: opts.nodeInfo.relay,
+                    direct_addrs: opts.nodeInfo.directAddrs,
+                    ttl,
+                };
+                await transport.unary('PublicationService', 'register_endpoint', request);
+                opts.logger?.info(`Registered endpoint with @aster: ${svcName} (${opts.nodeInfo.nodeId.slice(0, 12)})`);
+            }
+            catch (e) {
+                opts.logger?.warn(`Failed to register ${svcName} with @aster: ${e}`);
+            }
+        }
+    }
+    finally {
+        await transport.close();
+    }
+}
+// ── startRegistrationLoop ────────────────────────────────────────────────────
+/**
+ * Start the background registration loop.
+ *
+ * Registers endpoints with @aster immediately (after a 2 s startup
+ * delay), then re-registers at 75% of TTL to keep leases alive.
+ *
+ * Returns an `AbortController` -- call `.abort()` to stop the loop.
+ */
+export function startRegistrationLoop(opts) {
+    const abort = new AbortController();
+    const ttl = opts.ttl ?? 300;
+    const intervalMs = ttl * 0.75 * 1000;
+    const run = async () => {
+        // Wait for the server to be fully ready
+        await sleep(2000, abort.signal);
+        if (abort.signal.aborted)
+            return;
+        while (!abort.signal.aborted) {
+            try {
+                await registerEndpoints(opts, ttl);
+            }
+            catch (e) {
+                if (abort.signal.aborted)
+                    return;
+                opts.logger?.info(`@aster registration failed: ${e}`);
+            }
+            // Wait before re-registering
+            await sleep(intervalMs, abort.signal);
+        }
+    };
+    // Fire and forget -- the caller controls lifetime via AbortController
+    run().catch(() => { });
+    return abort;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Sleep that respects abort signal. */
+function sleep(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"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"}

package/dist/registry/acl.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Registry ACL — access control list for registry doc entries.
+ *
+ * Mirrors bindings/python/aster/registry/acl.py.
+ *
+ * Starts in open mode (all authors trusted). When the first ACL
+ * entry is set, switches to restricted mode.
+ */
+/** Doc handle interface for ACL operations. */
+interface AclDoc {
+    setBytes(authorHex: string, key: string, value: Uint8Array): Promise<string>;
+    getExact(authorHex: string, key: string): Promise<Uint8Array | null>;
+}
+/**
+ * Registry ACL — filters doc entries by trusted authors.
+ */
+export declare class RegistryACL {
+    private writers;
+    private readers;
+    private admins;
+    private _restricted;
+    /** Whether ACL is in restricted mode. */
+    get restricted(): boolean;
+    /** Check if an author is a trusted writer. */
+    isTrustedWriter(authorId: string): boolean;
+    /** Check if an author is a trusted reader. */
+    isTrustedReader(authorId: string): boolean;
+    /**
+     * Filter entries to only those from trusted authors.
+     *
+     * @param entries - Array of [authorId, value] pairs
+     * @returns Filtered entries
+     */
+    filterTrusted<T extends {
+        authorId: string;
+    }>(entries: T[]): T[];
+    /** Add a writer and switch to restricted mode. */
+    addWriter(authorId: string, doc?: AclDoc, adminAuthorId?: string): Promise<void>;
+    /** Add a reader. */
+    addReader(authorId: string): void;
+    /** Add an admin. */
+    addAdmin(authorId: string): void;
+    /** Remove a writer from the ACL. */
+    removeWriter(authorId: string): void;
+    /** Get all writers. */
+    getWriters(): string[];
+    /** Get all readers. */
+    getReaders(): string[];
+    /** Get all admins. */
+    getAdmins(): string[];
+    /**
+     * Reload ACL state from the registry doc.
+     */
+    reload(doc: AclDoc, authorId: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=acl.d.ts.map

package/dist/registry/acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../../src/registry/acl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,+CAA+C;AAC/C,UAAU,MAAM;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CACtE;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAAS;IAE5B,yCAAyC;IACzC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,8CAA8C;IAC9C,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAK1C,8CAA8C;IAC9C,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAK1C;;;;;OAKG;IACH,aAAa,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE;IAKhE,kDAAkD;IAC5C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtF,oBAAoB;IACpB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKjC,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKhC,oCAAoC;IACpC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,uBAAuB;IACvB,UAAU,IAAI,MAAM,EAAE;IAItB,uBAAuB;IACvB,UAAU,IAAI,MAAM,EAAE;IAItB,sBAAsB;IACtB,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB3D"}