@layervai/qurl 0.6.0 → 2.0.0

package/dist/cjs/node/qv2.js

@@ -7,6 +7,7 @@ exports.x25519PublicFromPrivate = x25519PublicFromPrivate;
 exports.strictBase64Url = strictBase64Url;
 const node_crypto_1 = require("node:crypto");
 const strict_json_js_1 = require("./strict-json.js");
+const crid_js_1 = require("../crid.js");
 const TRANSPORT_PREFIX = "qv2t1";
 const FRAGMENT_PREFIX = "qv2";
 const TRANSPORT_MAX_LENGTH = 6_826;
@@ -30,7 +31,7 @@ const CLAIM_KEYS = new Set([
     "qurl_user_public_key_b64",
 ]);
 const REQUIRED_CLAIM_KEYS = [...CLAIM_KEYS].filter((key) => key !== "cell_id");
-function verifyQv2Link(qurl, issuers) {
+function verifyQv2Link(qurl, issuers, expectedCRID) {
     const hash = qurl.indexOf("#");
     if (hash < 0)
         throw new Error("qURL link has no credential fragment");
@@ -45,6 +46,18 @@ function verifyQv2Link(qurl, issuers) {
     const claims = parseClaims(decodeCanonicalBase64Url(claimsB64));
     const secret = parseAndWipeSecret(decodeCanonicalBase64Url(secretB64));
     verifyIssuerClaims(claimsB64, signatureB64, issuers, claims);
+    if (expectedCRID !== undefined) {
+        const expected = (0, crid_js_1.parseCrid)(expectedCRID, true);
+        if (!expected)
+            throw new Error("invalid or unsupported expected CRID");
+        // The native verifier is synchronous; the portable helper uses WebCrypto.
+        const digest = (0, node_crypto_1.createHash)("sha256")
+            .update(crid_js_1.CRID_DOMAIN)
+            .update(decodeCanonicalBase64Url(claims.resourcePublicKeyB64))
+            .digest();
+        if (!(0, node_crypto_1.timingSafeEqual)(expected, digest.subarray(0, expected.length)))
+            throw new Error("qURL resource key does not match the expected CRID");
+    }
     const privateKey = decodeCanonicalBase64Url(secret.qurlUserPrivateKeyB64);
     let retainPrivateKey = false;
     try {
@@ -63,6 +76,7 @@ function verifyQv2Link(qurl, issuers) {
                 kid: claims.kid,
                 cellPublicKey: decodeX25519(claims.cellPublicKeyB64, "cell public key"),
                 resourcePublicKeyB64: claims.resourcePublicKeyB64,
+                relayUrl: claims.relayUrl,
             },
             devicePrivateKey: privateKey,
         };
@@ -207,7 +221,6 @@ function parseClaims(raw) {
     if (resourcePublic.byteLength < 80 || resourcePublic.byteLength > 160) {
         throw new Error("resource public key has an invalid length");
     }
-    requireNonEmptyString(value.relay_url, "relay URL");
     // cell_id is descriptive deployment metadata, not a security identity. The
     // signed 32-byte cell public key selects and then fully binds the UDP peer.
     if ("cell_id" in value && typeof value.cell_id !== "string") {
@@ -218,6 +231,7 @@ function parseClaims(raw) {
         cellPublicKeyB64,
         resourcePublicKeyB64,
         qurlUserPublicKeyB64: qurlPublic,
+        relayUrl: requireNonEmptyString(value.relay_url, "relay URL"),
     };
 }
 function verifyIssuerClaims(claimsB64, signatureB64, issuers, parsedClaims) {

package/dist/cjs/node/relay.d.ts

@@ -0,0 +1,12 @@
+import { type NHPMessage } from "./nhp-wire.js";
+export declare class RelayError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string, options?: ErrorOptions);
+}
+/** Call only after verifying the issuer signature over the relay URL. */
+export declare function validateRelayURL(value: string, allowlist: readonly string[]): URL;
+export declare function readBoundedBody(response: Response, limit: number): Promise<Uint8Array>;
+export declare function relayKnock(relayURL: string, allowlist: readonly string[], serverPublicKey: Uint8Array, devicePrivateKey: Uint8Array, body: Uint8Array, options?: {
+    signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+}): Promise<NHPMessage>;

package/dist/cjs/node/relay.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayError = void 0;
+exports.validateRelayURL = validateRelayURL;
+exports.readBoundedBody = readBoundedBody;
+exports.relayKnock = relayKnock;
+const deployment_js_1 = require("./deployment.js");
+const nhp_wire_js_1 = require("./nhp-wire.js");
+class RelayError extends Error {
+    status;
+    constructor(status, message, options) {
+        super(message, options);
+        this.status = status;
+        this.name = "RelayError";
+    }
+}
+exports.RelayError = RelayError;
+/** Call only after verifying the issuer signature over the relay URL. */
+function validateRelayURL(value, allowlist) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" ||
+        url.username ||
+        url.password ||
+        !url.hostname ||
+        !allowlist.some((entry) => {
+            const host = entry.trim().toLowerCase();
+            return (host === url.host.toLowerCase() ||
+                host === url.hostname.toLowerCase() ||
+                (url.port === "" && host === `${url.hostname.toLowerCase()}:443`));
+        }))
+        throw new Error("qURL relay URL is not permitted by deployment trust");
+    if (url.search || url.hash)
+        throw new Error("qURL relay base URL must not contain a query or fragment");
+    return url;
+}
+async function readBoundedBody(response, limit) {
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return Buffer.concat(chunks, length);
+            length += value.byteLength;
+            if (length > limit)
+                throw new Error("qURL HTTP response exceeds its size limit");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+async function relayKnock(relayURL, allowlist, serverPublicKey, devicePrivateKey, body, options = {}) {
+    let base;
+    try {
+        base = validateRelayURL(relayURL, allowlist);
+    }
+    catch (cause) {
+        throw new RelayError(0, "qURL relay URL is invalid or not trusted", { cause });
+    }
+    options.signal?.throwIfAborted();
+    const built = (0, nhp_wire_js_1.buildNHPMessage)({ type: nhp_wire_js_1.NHP_TYPE_KNOCK, serverPublicKey, devicePrivateKey, body });
+    let packet;
+    try {
+        const url = `${base.href.replace(/\/+$/, "")}/relay/${(0, deployment_js_1.fingerprintKey)(serverPublicKey)}`;
+        let response;
+        try {
+            response = await (options.fetch ?? globalThis.fetch)(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/octet-stream" },
+                body: Buffer.from(built.packet),
+                redirect: "error",
+                signal: options.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(15_000)])
+                    : AbortSignal.timeout(15_000),
+            });
+        }
+        catch (cause) {
+            options.signal?.throwIfAborted();
+            throw new RelayError(0, "qURL relay transport failed", { cause });
+        }
+        if (response.status !== 200) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new RelayError(response.status, "qURL relay returned an unexpected HTTP status");
+        }
+        try {
+            packet = await readBoundedBody(response, nhp_wire_js_1.NHP_PACKET_SIZE);
+            const reply = (0, nhp_wire_js_1.decryptNHPReply)(devicePrivateKey, serverPublicKey, packet);
+            if (reply.type === nhp_wire_js_1.NHP_TYPE_COOKIE)
+                return reply;
+            if (reply.type !== nhp_wire_js_1.NHP_TYPE_ACK || reply.counter !== built.counter) {
+                reply.body.fill(0);
+                throw new Error("NHP relay reply does not match the request");
+            }
+            return reply;
+        }
+        catch (cause) {
+            options.signal?.throwIfAborted();
+            throw new RelayError(200, "qURL relay reply is invalid", { cause });
+        }
+    }
+    finally {
+        built.packet.fill(0);
+        packet?.fill(0);
+    }
+}

package/dist/cjs/node/sealed-agent-state.d.ts

@@ -0,0 +1,19 @@
+import { FileAgentState, type AgentStateCodec } from "./file-agent-state.js";
+import { type StrictJsonValue } from "./strict-json.js";
+export interface AgentStateKeyBinding {
+    purpose: string;
+    envelopeVersion: number;
+    providerID: string;
+    agentID: string;
+}
+export interface WrappedAgentStateKey {
+    version: number;
+    ciphertext: Uint8Array;
+    metadata?: StrictJsonValue;
+}
+export interface AgentStateKeyWrapper {
+    wrapKey(key: Uint8Array, binding: AgentStateKeyBinding, signal?: AbortSignal): Promise<WrappedAgentStateKey>;
+    unwrapKey(wrapped: WrappedAgentStateKey, binding: AgentStateKeyBinding, signal?: AbortSignal): Promise<Uint8Array>;
+}
+export declare function createSealedAgentStateCodec(providerID: string, wrapper: AgentStateKeyWrapper, expectedAgentID?: string): AgentStateCodec;
+export declare function openSealedFileAgentState(path: string, providerID: string, wrapper: AgentStateKeyWrapper, expectedAgentID?: string): FileAgentState;

package/dist/cjs/node/sealed-agent-state.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSealedAgentStateCodec = createSealedAgentStateCodec;
+exports.openSealedFileAgentState = openSealedFileAgentState;
+const node_crypto_1 = require("node:crypto");
+const agent_state_js_1 = require("./agent-state.js");
+const file_agent_state_js_1 = require("./file-agent-state.js");
+const strict_json_js_1 = require("./strict-json.js");
+const PURPOSE = "qurl-go/agent-state";
+function base64(value, maximum) {
+    if (typeof value !== "string")
+        throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE");
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.toString("base64") !== value || bytes.length === 0 || bytes.length > maximum)
+        throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE");
+    return bytes;
+}
+// Go authenticates compact RawMessage bytes: keep key order and number lexemes.
+function compactMetadata(raw) {
+    return raw.replace(/"(?:\\.|[^"\\])*"|\s+/g, (token) => token.startsWith('"')
+        ? token.replace(/[<>&\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`)
+        : "");
+}
+function wrappedWire(wrapped) {
+    if (!Number.isSafeInteger(wrapped.version) ||
+        wrapped.version < 1 ||
+        !(wrapped.ciphertext instanceof Uint8Array) ||
+        wrapped.ciphertext.length === 0 ||
+        wrapped.ciphertext.length > 65536)
+        throw new agent_state_js_1.AgentStateError("INVALID_WRAPPED_KEY");
+    const metadata = wrapped.metadata === undefined
+        ? undefined
+        : (0, strict_json_js_1.parseStrictJson)((0, agent_state_js_1.encodeAgentJSON)(wrapped.metadata), 16384);
+    return {
+        version: wrapped.version,
+        ciphertext: Buffer.from(wrapped.ciphertext).toString("base64"),
+        ...(metadata === undefined ? {} : { metadata }),
+    };
+}
+function aad(binding, wrapped, metadataRaw) {
+    const raw = (0, agent_state_js_1.encodeAgentJSON)({
+        purpose: binding.purpose,
+        envelope_version: binding.envelopeVersion,
+        provider_id: binding.providerID,
+        agent_id: binding.agentID,
+        wrapped_key: { version: wrapped.version, ciphertext: wrapped.ciphertext },
+    });
+    const metadata = metadataRaw === undefined
+        ? wrapped.metadata === undefined
+            ? undefined
+            : (0, agent_state_js_1.encodeAgentJSON)(wrapped.metadata).toString()
+        : compactMetadata(metadataRaw);
+    // wrapped_key is the final field; raw ends with its closing brace and the envelope brace.
+    return metadata === undefined
+        ? raw
+        : Buffer.concat([raw.subarray(0, -2), Buffer.from(',"metadata":' + metadata + "}}")]);
+}
+function decrypt(key, nonce, ciphertext, associated) {
+    if (key.length !== 32 || nonce.length !== 12 || ciphertext.length < 16)
+        throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE");
+    const cipher = (0, node_crypto_1.createDecipheriv)("aes-256-gcm", key, nonce);
+    cipher.setAAD(associated);
+    cipher.setAuthTag(ciphertext.subarray(-16));
+    let plain;
+    try {
+        plain = cipher.update(ciphertext.subarray(0, -16));
+        const final = cipher.final();
+        const result = Buffer.concat([plain, final]);
+        final.fill(0);
+        return result;
+    }
+    catch (cause) {
+        throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE", { cause });
+    }
+    finally {
+        plain?.fill(0);
+    }
+}
+function createSealedAgentStateCodec(providerID, wrapper, expectedAgentID) {
+    if (!/^[a-z][a-z0-9]*([.-][a-z0-9]+)*$/.test(providerID) ||
+        providerID.length > 64 ||
+        !wrapper ||
+        typeof wrapper.wrapKey !== "function" ||
+        typeof wrapper.unwrapKey !== "function")
+        throw new agent_state_js_1.AgentStateError("INVALID_WRAPPER_CONFIG");
+    const bindingFor = (agentID) => {
+        if (typeof agentID !== "string" ||
+            !agentID ||
+            agentID.trim() !== agentID ||
+            Buffer.byteLength(agentID) > 256 ||
+            [...agentID].some((ch) => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127) ||
+            (expectedAgentID !== undefined && expectedAgentID !== agentID))
+            throw new agent_state_js_1.AgentStateError("ENVELOPE_IDENTITY_MISMATCH");
+        return { purpose: PURPOSE, envelopeVersion: 1, providerID, agentID };
+    };
+    if (expectedAgentID !== undefined)
+        bindingFor(expectedAgentID);
+    return {
+        async encode(state, signal) {
+            signal?.throwIfAborted();
+            const raw = (0, agent_state_js_1.encodeAgentState)(state);
+            const key = (0, node_crypto_1.randomBytes)(32);
+            const copy = Buffer.from(key);
+            try {
+                const binding = bindingFor(state.agent_id);
+                const wrapped = wrappedWire(await wrapper.wrapKey(copy, { ...binding }, signal));
+                signal?.throwIfAborted();
+                const nonce = (0, node_crypto_1.randomBytes)(12);
+                const associated = aad(binding, wrapped);
+                const cipher = (0, node_crypto_1.createCipheriv)("aes-256-gcm", key, nonce);
+                cipher.setAAD(associated);
+                const ciphertext = Buffer.concat([cipher.update(raw), cipher.final(), cipher.getAuthTag()]);
+                const recovered = await wrapper.unwrapKey({
+                    version: wrapped.version,
+                    ciphertext: Buffer.from(wrapped.ciphertext, "base64"),
+                    ...(wrapped.metadata === undefined ? {} : { metadata: wrapped.metadata }),
+                }, { ...binding }, signal);
+                let check;
+                try {
+                    signal?.throwIfAborted();
+                    check = decrypt(recovered, nonce, ciphertext, associated);
+                    if (!check.equals(raw))
+                        throw new agent_state_js_1.AgentStateError("ENVELOPE_ROUNDTRIP");
+                }
+                finally {
+                    check?.fill(0);
+                    recovered.fill(0);
+                }
+                const envelope = (0, agent_state_js_1.encodeAgentJSON)({
+                    version: 1,
+                    purpose: PURPOSE,
+                    agent_id: binding.agentID,
+                    provider_id: providerID,
+                    wrapped_key: wrapped,
+                    nonce: nonce.toString("base64"),
+                    ciphertext: ciphertext.toString("base64"),
+                });
+                (0, strict_json_js_1.parseStrictJson)(envelope, 2 << 20);
+                return envelope;
+            }
+            finally {
+                raw.fill(0);
+                key.fill(0);
+                copy.fill(0);
+            }
+        },
+        async decode(raw, signal) {
+            signal?.throwIfAborted();
+            const metadataMembers = new Map();
+            const envelope = (0, agent_state_js_1.exactObject)((0, strict_json_js_1.parseStrictJson)(raw, 2 << 20, (object, key, value) => {
+                if (key === "metadata")
+                    metadataMembers.set(object, value);
+            }), "version purpose agent_id provider_id wrapped_key nonce ciphertext");
+            if (envelope.version !== 1n ||
+                envelope.purpose !== PURPOSE ||
+                envelope.provider_id !== providerID)
+                throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE");
+            const binding = bindingFor(envelope.agent_id);
+            const record = (0, agent_state_js_1.exactObject)(envelope.wrapped_key, "version ciphertext metadata");
+            if (typeof record.version !== "bigint" ||
+                record.version < 1n ||
+                record.version > BigInt(Number.MAX_SAFE_INTEGER))
+                throw new agent_state_js_1.AgentStateError("INVALID_WRAPPED_KEY");
+            const wrapped = {
+                version: Number(record.version),
+                ciphertext: base64(record.ciphertext, 65536),
+                ...(record.metadata === undefined ? {} : { metadata: record.metadata }),
+            };
+            const wire = wrappedWire(wrapped);
+            const nonce = base64(envelope.nonce, 12);
+            const ciphertext = base64(envelope.ciphertext, (1 << 20) + 16);
+            if (nonce.length !== 12 || ciphertext.length < 16)
+                throw new agent_state_js_1.AgentStateError("INVALID_ENVELOPE");
+            const key = await wrapper.unwrapKey(wrapped, { ...binding }, signal);
+            let plaintext;
+            try {
+                signal?.throwIfAborted();
+                plaintext = decrypt(key, nonce, ciphertext, aad(binding, wire, metadataMembers.get(record)));
+                const state = (0, agent_state_js_1.decodeAgentState)(plaintext);
+                if (state.agent_id !== binding.agentID)
+                    throw new agent_state_js_1.AgentStateError("ENVELOPE_IDENTITY_MISMATCH");
+                return state;
+            }
+            finally {
+                key.fill(0);
+                plaintext?.fill(0);
+            }
+        },
+    };
+}
+function openSealedFileAgentState(path, providerID, wrapper, expectedAgentID) {
+    return new file_agent_state_js_1.FileAgentState(path, createSealedAgentStateCodec(providerID, wrapper, expectedAgentID));
+}

package/dist/cjs/node/strict-json.d.ts

@@ -6,7 +6,7 @@ export type StrictJsonValue = null | boolean | number | bigint | string | Strict
  * integer ambiguity. NHP uses uint64 session identifiers, so integral values
  * outside Number's safe range remain bigint instead of losing wire bytes.
  */
-export declare function parseStrictJson(input: Uint8Array, maxBytes: number): StrictJsonValue;
+export declare function parseStrictJson(input: Uint8Array, maxBytes: number, onMember?: (object: object, key: string, raw: string) => void): StrictJsonValue;
 export declare function isStrictJsonObject(value: StrictJsonValue | undefined): value is {
     [key: string]: StrictJsonValue;
 };

package/dist/cjs/node/strict-json.js

@@ -9,11 +9,11 @@ const JSON_NUMBER = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
  * integer ambiguity. NHP uses uint64 session identifiers, so integral values
  * outside Number's safe range remain bigint instead of losing wire bytes.
  */
-function parseStrictJson(input, maxBytes) {
+function parseStrictJson(input, maxBytes, onMember) {
     if (input.byteLength > maxBytes)
         throw new Error(`JSON exceeds ${maxBytes}-byte limit`);
     const text = new TextDecoder("utf-8", { fatal: true }).decode(input);
-    const parser = new StrictJsonParser(text);
+    const parser = new StrictJsonParser(text, onMember);
     const value = parser.parseValue(0);
     parser.skipWhitespace();
     if (!parser.done)
@@ -22,9 +22,11 @@ function parseStrictJson(input, maxBytes) {
 }
 class StrictJsonParser {
     input;
+    onMember;
     #offset = 0;
-    constructor(input) {
+    constructor(input, onMember) {
         this.input = input;
+        this.onMember = onMember;
     }
     get done() {
         return this.#offset === this.input.length;
@@ -77,7 +79,10 @@ class StrictJsonParser {
             this.skipWhitespace();
             if (!this.consume(":"))
                 throw new Error("JSON object key has no value");
+            this.skipWhitespace();
+            const start = this.#offset;
             value[key] = this.parseValue(depth);
+            this.onMember?.(value, key, this.input.slice(start, this.#offset));
             this.skipWhitespace();
             if (this.consume("}"))
                 return value;

package/dist/cjs/node.d.ts

@@ -1,3 +1,17 @@
 export { createPortalOpener, PortalBusyError, PortalConfigurationError, PortalDenyError, PortalInvalidReplyError, PortalOpenerClosedError, PortalOpenerNotReadyError, PortalOpenerNotStartedError, PortalOpenTimeoutError, PortalRedirectError, PortalStateError, PortalTargetChangedError, PortalTooManyRedirectsError, PortalVerificationError, } from "./node/portal-opener.js";
 export type { CreatePortalOpenerOptions, PortalFetchOptions, PortalOpener, PortalOpenerFailureClass, PortalOpenerHealth, PortalOpenerState, PortalRequestBuilder, PortalStartOptions, } from "./node/portal-opener.js";
 export type { PortalDeployment, PortalDeploymentCell, PortalDeploymentIssuer, } from "./node/deployment.js";
+export { RelayError, validateRelayURL } from "./node/relay.js";
+export { createStaticProvider, createDiscoveryProvider, createHTTPManifestFetcher, } from "./node/provider.js";
+export type { PortalProvider, DiscoveryProviderOptions } from "./node/provider.js";
+export { AgentStateError, decodeAgentState, encodeAgentState } from "./node/agent-state.js";
+export type { AgentState, AgentAssignment, NHPUDPEndpoint, AgentStateStore, AssignmentRegistration, PendingAgentActivation, PendingAgentCompletion, PendingAgentCredentialRecovery, PendingAgentCredentialRecoveryIssue, } from "./node/agent-state.js";
+export type { AgentStateCodec } from "./node/file-agent-state.js";
+export type { AgentExchange, AgentTransport } from "./node/agent-transport.js";
+export { AgentTransportError } from "./node/agent-transport.js";
+export type { NHPMessage } from "./node/nhp-wire.js";
+export { FileAgentState } from "./node/file-agent-state.js";
+export { createSealedAgentStateCodec, openSealedFileAgentState, } from "./node/sealed-agent-state.js";
+export type { AgentStateKeyBinding, WrappedAgentStateKey, AgentStateKeyWrapper, } from "./node/sealed-agent-state.js";
+export { AgentRuntime, AgentLifecycleError, connectAgentRuntime, recoverAgentRuntime, } from "./node/agent-runtime.js";
+export type { AgentRuntimeOptions, AgentRecoveryOptions, AgentOTPChallenge, NativeAgentKnockOptions, NativeAgentGrant, NativeSessionReceipt, } from "./node/agent-runtime.js";

package/dist/cjs/node.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PortalVerificationError = exports.PortalTooManyRedirectsError = exports.PortalTargetChangedError = exports.PortalStateError = exports.PortalRedirectError = exports.PortalOpenTimeoutError = exports.PortalOpenerNotStartedError = exports.PortalOpenerNotReadyError = exports.PortalOpenerClosedError = exports.PortalInvalidReplyError = exports.PortalDenyError = exports.PortalConfigurationError = exports.PortalBusyError = exports.createPortalOpener = void 0;
+exports.recoverAgentRuntime = exports.connectAgentRuntime = exports.AgentLifecycleError = exports.AgentRuntime = exports.openSealedFileAgentState = exports.createSealedAgentStateCodec = exports.FileAgentState = exports.AgentTransportError = exports.encodeAgentState = exports.decodeAgentState = exports.AgentStateError = exports.createHTTPManifestFetcher = exports.createDiscoveryProvider = exports.createStaticProvider = exports.validateRelayURL = exports.RelayError = exports.PortalVerificationError = exports.PortalTooManyRedirectsError = exports.PortalTargetChangedError = exports.PortalStateError = exports.PortalRedirectError = exports.PortalOpenTimeoutError = exports.PortalOpenerNotStartedError = exports.PortalOpenerNotReadyError = exports.PortalOpenerClosedError = exports.PortalInvalidReplyError = exports.PortalDenyError = exports.PortalConfigurationError = exports.PortalBusyError = exports.createPortalOpener = void 0;
 var portal_opener_js_1 = require("./node/portal-opener.js");
 Object.defineProperty(exports, "createPortalOpener", { enumerable: true, get: function () { return portal_opener_js_1.createPortalOpener; } });
 Object.defineProperty(exports, "PortalBusyError", { enumerable: true, get: function () { return portal_opener_js_1.PortalBusyError; } });
@@ -16,3 +16,26 @@ Object.defineProperty(exports, "PortalStateError", { enumerable: true, get: func
 Object.defineProperty(exports, "PortalTargetChangedError", { enumerable: true, get: function () { return portal_opener_js_1.PortalTargetChangedError; } });
 Object.defineProperty(exports, "PortalTooManyRedirectsError", { enumerable: true, get: function () { return portal_opener_js_1.PortalTooManyRedirectsError; } });
 Object.defineProperty(exports, "PortalVerificationError", { enumerable: true, get: function () { return portal_opener_js_1.PortalVerificationError; } });
+var relay_js_1 = require("./node/relay.js");
+Object.defineProperty(exports, "RelayError", { enumerable: true, get: function () { return relay_js_1.RelayError; } });
+Object.defineProperty(exports, "validateRelayURL", { enumerable: true, get: function () { return relay_js_1.validateRelayURL; } });
+var provider_js_1 = require("./node/provider.js");
+Object.defineProperty(exports, "createStaticProvider", { enumerable: true, get: function () { return provider_js_1.createStaticProvider; } });
+Object.defineProperty(exports, "createDiscoveryProvider", { enumerable: true, get: function () { return provider_js_1.createDiscoveryProvider; } });
+Object.defineProperty(exports, "createHTTPManifestFetcher", { enumerable: true, get: function () { return provider_js_1.createHTTPManifestFetcher; } });
+var agent_state_js_1 = require("./node/agent-state.js");
+Object.defineProperty(exports, "AgentStateError", { enumerable: true, get: function () { return agent_state_js_1.AgentStateError; } });
+Object.defineProperty(exports, "decodeAgentState", { enumerable: true, get: function () { return agent_state_js_1.decodeAgentState; } });
+Object.defineProperty(exports, "encodeAgentState", { enumerable: true, get: function () { return agent_state_js_1.encodeAgentState; } });
+var agent_transport_js_1 = require("./node/agent-transport.js");
+Object.defineProperty(exports, "AgentTransportError", { enumerable: true, get: function () { return agent_transport_js_1.AgentTransportError; } });
+var file_agent_state_js_1 = require("./node/file-agent-state.js");
+Object.defineProperty(exports, "FileAgentState", { enumerable: true, get: function () { return file_agent_state_js_1.FileAgentState; } });
+var sealed_agent_state_js_1 = require("./node/sealed-agent-state.js");
+Object.defineProperty(exports, "createSealedAgentStateCodec", { enumerable: true, get: function () { return sealed_agent_state_js_1.createSealedAgentStateCodec; } });
+Object.defineProperty(exports, "openSealedFileAgentState", { enumerable: true, get: function () { return sealed_agent_state_js_1.openSealedFileAgentState; } });
+var agent_runtime_js_1 = require("./node/agent-runtime.js");
+Object.defineProperty(exports, "AgentRuntime", { enumerable: true, get: function () { return agent_runtime_js_1.AgentRuntime; } });
+Object.defineProperty(exports, "AgentLifecycleError", { enumerable: true, get: function () { return agent_runtime_js_1.AgentLifecycleError; } });
+Object.defineProperty(exports, "connectAgentRuntime", { enumerable: true, get: function () { return agent_runtime_js_1.connectAgentRuntime; } });
+Object.defineProperty(exports, "recoverAgentRuntime", { enumerable: true, get: function () { return agent_runtime_js_1.recoverAgentRuntime; } });

package/dist/cjs/share.d.ts

@@ -0,0 +1,56 @@
+import { ERROR_CODE_CRID_MISMATCH, ERROR_CODE_INVALID_CRID, ERROR_CODE_INVALID_CRID_KEY, ERROR_CODE_MISSING_CRID, QURLError } from "./errors.js";
+export type CRIDVerificationErrorCode = typeof ERROR_CODE_MISSING_CRID | typeof ERROR_CODE_INVALID_CRID | typeof ERROR_CODE_INVALID_CRID_KEY | typeof ERROR_CODE_CRID_MISMATCH;
+/** A local, fail-closed CRID verification failure. */
+export declare class CRIDVerificationError extends QURLError {
+    readonly code: CRIDVerificationErrorCode;
+    constructor(code: CRIDVerificationErrorCode, message: string);
+}
+export interface ShareLinkInit {
+    link: string;
+    qurlId?: string;
+    crid?: string;
+    type?: string;
+    expiresAt?: Date;
+    expiresInSeconds?: number;
+    singleUse?: boolean;
+}
+/** Credential-redacted, JSON-safe representation returned by {@link ShareLink.toJSON}. */
+export interface ShareLinkJSON {
+    link: "[redacted]";
+    qurlId?: string;
+    crid?: string;
+    type?: string;
+    expiresAt?: string;
+    expiresInSeconds?: number;
+    singleUse?: boolean;
+}
+/**
+ * A freshly minted, one-time-returned access link for an existing resource.
+ * Instances are frozen during construction and are not designed for subclassing.
+ */
+export declare class ShareLink {
+    #private;
+    /**
+     * The one-time secret share link. This property is deliberately
+     * non-enumerable: read it directly instead of spreading or cloning the object.
+     */
+    readonly link: string;
+    /** Token ID when supplied by the service. */
+    readonly qurlId?: string;
+    readonly crid?: string;
+    readonly type?: string;
+    readonly expiresInSeconds?: number;
+    /** Whether the link is single-use; undefined when the service omits the field. */
+    readonly singleUse?: boolean;
+    constructor(init: ShareLinkInit);
+    /** Effective expiry as a defensive copy; mutating it does not change this share. */
+    get expiresAt(): Date | undefined;
+    /** Serialize safe metadata while redacting the one-time-returned credential. */
+    toJSON(): ShareLinkJSON;
+    /**
+     * Verify that this response's CRID was derived from a DER SubjectPublicKeyInfo
+     * already trusted by the caller. This binds the response CRID to that key; it
+     * does not independently prove that the secret link fragment belongs to it.
+     */
+    verifyCrid(derSpki: ArrayBuffer | ArrayBufferView): Promise<void>;
+}