@layervai/qurl 0.3.0 → 0.4.0

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

@@ -0,0 +1,38 @@
+import type { KeyObject } from "node:crypto";
+export interface VerifiedQv2Link {
+    readonly claimsB64: string;
+    readonly signatureB64: string;
+    readonly claims: {
+        readonly kid: string;
+        readonly cellPublicKey: Uint8Array;
+        readonly resourcePublicKeyB64: string;
+    };
+    readonly devicePrivateKey: Uint8Array;
+}
+export declare function verifyQv2Link(qurl: string, issuers: ReadonlyMap<string, KeyObject>): VerifiedQv2Link;
+export declare function issuerKeyFromSpki(spki: Uint8Array): KeyObject;
+export declare function x25519PublicFromPrivate(raw: Uint8Array): Uint8Array;
+export declare function strictBase64Url(value: string): Uint8Array;
+declare function decodeTransport(value: string): string;
+type ParsedClaims = {
+    kid: string;
+    cellPublicKeyB64: string;
+    resourcePublicKeyB64: string;
+    qurlUserPublicKeyB64: string;
+};
+declare function parseClaims(raw: Uint8Array): ParsedClaims;
+declare function verifyIssuerClaims(claimsB64: string, signatureB64: string, issuers: ReadonlyMap<string, KeyObject>, parsedClaims?: ParsedClaims): ParsedClaims;
+declare function parseSecret(raw: Uint8Array): {
+    qurlUserPrivateKeyB64: string;
+};
+declare function parseAndWipeSecret(raw: Uint8Array): {
+    qurlUserPrivateKeyB64: string;
+};
+export declare const qv2Testing: {
+    decodeTransport: typeof decodeTransport;
+    parseClaims: typeof parseClaims;
+    parseSecret: typeof parseSecret;
+    parseAndWipeSecret: typeof parseAndWipeSecret;
+    verifyIssuerClaims: typeof verifyIssuerClaims;
+};
+export {};

package/dist/cjs/node/qv2.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qv2Testing = void 0;
+exports.verifyQv2Link = verifyQv2Link;
+exports.issuerKeyFromSpki = issuerKeyFromSpki;
+exports.x25519PublicFromPrivate = x25519PublicFromPrivate;
+exports.strictBase64Url = strictBase64Url;
+const node_crypto_1 = require("node:crypto");
+const strict_json_js_1 = require("./strict-json.js");
+const TRANSPORT_PREFIX = "qv2t1";
+const FRAGMENT_PREFIX = "qv2";
+const TRANSPORT_MAX_LENGTH = 6_826;
+const TRANSPORT_COMPONENT_MAX = 240;
+const SIGNING_DOMAIN = Buffer.from("NHP-QURL-V2-ISSUER\0", "utf8");
+const P256_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
+const P256_HALF_ORDER = P256_ORDER >> 1n;
+const X25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+const CLAIM_KEYS = new Set([
+    "v",
+    "iss",
+    "kid",
+    "iat",
+    "nbf",
+    "exp",
+    "jti",
+    "cell_public_key_b64",
+    "cell_id",
+    "relay_url",
+    "resource_public_key_b64",
+    "qurl_user_public_key_b64",
+]);
+const REQUIRED_CLAIM_KEYS = [...CLAIM_KEYS].filter((key) => key !== "cell_id");
+function verifyQv2Link(qurl, issuers) {
+    const hash = qurl.indexOf("#");
+    if (hash < 0)
+        throw new Error("qURL link has no credential fragment");
+    const canonical = decodeTransport(qurl.slice(hash + 1));
+    const parts = canonical.split(".");
+    if (parts.length !== 4 || parts[0] !== FRAGMENT_PREFIX || parts.slice(1).some((p) => p === "")) {
+        throw new Error("invalid qURL credential fragment");
+    }
+    const [, claimsB64, secretB64, signatureB64] = parts;
+    // Match Go ParseFragment -> Verify ordering: strict claims and secret parsing
+    // precede signature/trust errors for an otherwise valid outer transport.
+    const claims = parseClaims(decodeCanonicalBase64Url(claimsB64));
+    const secret = parseAndWipeSecret(decodeCanonicalBase64Url(secretB64));
+    verifyIssuerClaims(claimsB64, signatureB64, issuers, claims);
+    const privateKey = decodeCanonicalBase64Url(secret.qurlUserPrivateKeyB64);
+    let retainPrivateKey = false;
+    try {
+        if (privateKey.byteLength !== 32)
+            throw new Error("qURL private key has an invalid length");
+        const derivedPublicKey = x25519PublicFromPrivate(privateKey);
+        const signedPublicKey = decodeX25519(claims.qurlUserPublicKeyB64, "qURL public key");
+        if (!(0, node_crypto_1.timingSafeEqual)(derivedPublicKey, signedPublicKey)) {
+            throw new Error("qURL private key does not match its signed public key");
+        }
+        retainPrivateKey = true;
+        return {
+            claimsB64,
+            signatureB64,
+            claims: {
+                kid: claims.kid,
+                cellPublicKey: decodeX25519(claims.cellPublicKeyB64, "cell public key"),
+                resourcePublicKeyB64: claims.resourcePublicKeyB64,
+            },
+            devicePrivateKey: privateKey,
+        };
+    }
+    finally {
+        if (!retainPrivateKey)
+            privateKey.fill(0);
+    }
+}
+function issuerKeyFromSpki(spki) {
+    const key = (0, node_crypto_1.createPublicKey)({ key: spki, format: "der", type: "spki" });
+    const canonical = key.export({ format: "der", type: "spki" });
+    const supplied = Buffer.from(spki.buffer, spki.byteOffset, spki.byteLength);
+    // Node accepts a valid SPKI followed by unrelated DER bytes. Go's
+    // x509.ParsePKIXPublicKey requires the complete input to contain one key, so
+    // require the same byte-exact consumption before this key becomes trust.
+    if (canonical.byteLength !== supplied.byteLength || !canonical.equals(supplied)) {
+        throw new Error("issuer key must contain exactly one canonical SPKI public key");
+    }
+    if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+        throw new Error("issuer key must be a P-256 SPKI public key");
+    }
+    return key;
+}
+function x25519PublicFromPrivate(raw) {
+    if (raw.byteLength !== 32)
+        throw new Error("X25519 private key must be 32 bytes");
+    const der = Buffer.alloc(X25519_PKCS8_PREFIX.byteLength + raw.byteLength);
+    X25519_PKCS8_PREFIX.copy(der);
+    der.set(raw, X25519_PKCS8_PREFIX.byteLength);
+    let privateKey;
+    try {
+        privateKey = (0, node_crypto_1.createPrivateKey)({ key: der, format: "der", type: "pkcs8" });
+    }
+    finally {
+        der.fill(0);
+    }
+    const spki = (0, node_crypto_1.createPublicKey)(privateKey).export({ format: "der", type: "spki" });
+    return new Uint8Array(spki.subarray(spki.byteLength - 32));
+}
+function strictBase64Url(value) {
+    return decodeCanonicalBase64Url(value);
+}
+function decodeTransport(value) {
+    if (value.length > TRANSPORT_MAX_LENGTH)
+        throw new Error("qURL transport exceeds its size limit");
+    const parts = value.split(".");
+    if (parts.length < 4 || parts[0] !== TRANSPORT_PREFIX) {
+        throw new Error("qURL does not use the qv2t1 credential transport");
+    }
+    const counts = [parseCount(parts[1], 26), parseCount(parts[2], 3), parseCount(parts[3], 1)];
+    if (parts.length !== 4 + counts[0] + counts[1] + counts[2]) {
+        throw new Error("qURL transport part count does not match its declarations");
+    }
+    let offset = 4;
+    const limits = [6_144, 512, 128];
+    const fields = counts.map((count, index) => {
+        const chunks = parts.slice(offset, offset + count);
+        offset += count;
+        let total = 0;
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            if (chunk.length === 0 ||
+                chunk.length > TRANSPORT_COMPONENT_MAX ||
+                (i < chunks.length - 1 && chunk.length !== TRANSPORT_COMPONENT_MAX) ||
+                !/^[A-Za-z0-9_-]+$/.test(chunk)) {
+                throw new Error("qURL transport has an invalid chunk");
+            }
+            total += chunk.length;
+            if (total > limits[index])
+                throw new Error("qURL transport field exceeds its size limit");
+        }
+        return chunks.join("");
+    });
+    return `${FRAGMENT_PREFIX}.${fields[0]}.${fields[1]}.${fields[2]}`;
+}
+function parseCount(value, maximum) {
+    if (!/^[1-9][0-9]*$/.test(value))
+        throw new Error("qURL transport count is not canonical");
+    const count = Number(value);
+    if (!Number.isSafeInteger(count) || count > maximum) {
+        throw new Error("qURL transport count exceeds its limit");
+    }
+    return count;
+}
+function decodeCanonicalBase64Url(value) {
+    if (value === "" || !/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1) {
+        throw new Error("value is not canonical unpadded base64url");
+    }
+    const decoded = Buffer.from(value, "base64url");
+    if (decoded.toString("base64url") !== value) {
+        decoded.fill(0);
+        throw new Error("value is not canonical unpadded base64url");
+    }
+    return decoded;
+}
+function decodeX25519(value, name) {
+    const decoded = decodeCanonicalBase64Url(value);
+    if (decoded.byteLength !== 32)
+        throw new Error(`${name} has an invalid length`);
+    return decoded;
+}
+function parseClaims(raw) {
+    const value = (0, strict_json_js_1.parseStrictJson)(raw, 4_608);
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value))
+        throw new Error("qURL claims must be one JSON object");
+    for (const key of Object.keys(value)) {
+        if (!CLAIM_KEYS.has(key))
+            throw new Error("qURL claims contain an unknown field");
+        if (value[key] === null)
+            throw new Error("qURL claims contain a null field");
+    }
+    for (const key of REQUIRED_CLAIM_KEYS) {
+        if (!(key in value))
+            throw new Error("qURL claims are missing a required field");
+    }
+    if (value.v !== 2n || value.iss !== "qurl-service")
+        throw new Error("qURL claims version or issuer is invalid");
+    const times = {
+        iat: 0n,
+        nbf: 0n,
+        exp: 0n,
+    };
+    for (const key of ["iat", "nbf", "exp"]) {
+        const item = value[key];
+        if (typeof item !== "bigint" || item <= 0n || item > 9999999999n) {
+            throw new Error("qURL claims contain an invalid time");
+        }
+        times[key] = item;
+    }
+    if (times.iat > times.exp || times.nbf > times.exp) {
+        throw new Error("qURL claims contain an invalid time window");
+    }
+    const kid = requireNonEmptyString(value.kid, "issuer key id");
+    requireNonEmptyString(value.jti, "qURL id");
+    const cellPublicKeyB64 = requireNonEmptyString(value.cell_public_key_b64, "cell public key");
+    decodeX25519(cellPublicKeyB64, "cell public key");
+    const qurlPublic = requireNonEmptyString(value.qurl_user_public_key_b64, "qURL public key");
+    decodeX25519(qurlPublic, "qURL public key");
+    const resourcePublicKeyB64 = requireNonEmptyString(value.resource_public_key_b64, "resource public key");
+    const resourcePublic = decodeCanonicalBase64Url(resourcePublicKeyB64);
+    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") {
+        throw new Error("qURL cell id must be a string");
+    }
+    return {
+        kid,
+        cellPublicKeyB64,
+        resourcePublicKeyB64,
+        qurlUserPublicKeyB64: qurlPublic,
+    };
+}
+function verifyIssuerClaims(claimsB64, signatureB64, issuers, parsedClaims) {
+    // Full-link verification supplies the claims it parsed before the secret so
+    // this shared verification path preserves Go's ParseFragment error order.
+    const claims = parsedClaims ?? parseClaims(decodeCanonicalBase64Url(claimsB64));
+    verifyParsedIssuerClaims(claims, claimsB64, signatureB64, issuers);
+    return claims;
+}
+function verifyParsedIssuerClaims(claims, claimsB64, signatureB64, issuers) {
+    const signature = decodeCanonicalBase64Url(signatureB64);
+    const issuer = issuers.get(claims.kid);
+    if (!issuer)
+        throw new Error("qURL uses an unknown issuer key id");
+    // Go resolves trust after base64 decoding but before raw signature shape
+    // validation. Preserve that error precedence for full-link verification.
+    validateRawP256Signature(signature);
+    const signingInput = Buffer.concat([SIGNING_DOMAIN, Buffer.from(claimsB64, "ascii")]);
+    if (!(0, node_crypto_1.verify)("sha256", signingInput, { key: issuer, dsaEncoding: "ieee-p1363" }, signature)) {
+        throw new Error("qURL issuer signature verification failed");
+    }
+}
+function parseSecret(raw) {
+    const value = (0, strict_json_js_1.parseStrictJson)(raw, 1_024);
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value) || Object.keys(value).length !== 1) {
+        throw new Error("qURL secret has an invalid object shape");
+    }
+    const qurlUserPrivateKeyB64 = requireNonEmptyString(value.qurl_user_private_key_b64, "qURL private key");
+    const privateKey = decodeCanonicalBase64Url(qurlUserPrivateKeyB64);
+    try {
+        if (privateKey.byteLength !== 32)
+            throw new Error("qURL private key has an invalid length");
+    }
+    finally {
+        privateKey.fill(0);
+    }
+    return { qurlUserPrivateKeyB64 };
+}
+function parseAndWipeSecret(raw) {
+    try {
+        return parseSecret(raw);
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+function requireNonEmptyString(value, name) {
+    if (typeof value !== "string" || value === "")
+        throw new Error(`${name} must be a non-empty string`);
+    return value;
+}
+function validateRawP256Signature(signature) {
+    if (signature.byteLength !== 64)
+        throw new Error("qURL signature must be 64 bytes");
+    const r = bytesToBigInt(signature.subarray(0, 32));
+    const s = bytesToBigInt(signature.subarray(32));
+    if (r <= 0n || r >= P256_ORDER || s <= 0n || s >= P256_ORDER) {
+        throw new Error("qURL signature scalar is outside the P-256 range");
+    }
+    if (s > P256_HALF_ORDER)
+        throw new Error("qURL signature is not low-S normalized");
+}
+function bytesToBigInt(value) {
+    return BigInt(`0x${Buffer.from(value).toString("hex")}`);
+}
+exports.qv2Testing = {
+    decodeTransport,
+    parseClaims,
+    parseSecret,
+    parseAndWipeSecret,
+    verifyIssuerClaims,
+};

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

@@ -0,0 +1,12 @@
+export type StrictJsonValue = null | boolean | number | bigint | string | StrictJsonValue[] | {
+    [key: string]: StrictJsonValue;
+};
+/**
+ * Parse a bounded JSON value without JavaScript's duplicate-key or unsafe-
+ * 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 isStrictJsonObject(value: StrictJsonValue | undefined): value is {
+    [key: string]: StrictJsonValue;
+};

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

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStrictJson = parseStrictJson;
+exports.isStrictJsonObject = isStrictJsonObject;
+const MAX_JSON_DEPTH = 32;
+const JSON_NUMBER = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+/**
+ * Parse a bounded JSON value without JavaScript's duplicate-key or unsafe-
+ * 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) {
+    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 value = parser.parseValue(0);
+    parser.skipWhitespace();
+    if (!parser.done)
+        throw new Error("trailing data after JSON value");
+    return value;
+}
+class StrictJsonParser {
+    input;
+    #offset = 0;
+    constructor(input) {
+        this.input = input;
+    }
+    get done() {
+        return this.#offset === this.input.length;
+    }
+    skipWhitespace() {
+        while (this.#offset < this.input.length) {
+            const code = this.input.charCodeAt(this.#offset);
+            if (code !== 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+                break;
+            this.#offset++;
+        }
+    }
+    parseValue(depth) {
+        if (depth > MAX_JSON_DEPTH)
+            throw new Error("JSON nesting is too deep");
+        this.skipWhitespace();
+        const token = this.input[this.#offset];
+        if (token === '"')
+            return this.parseString();
+        if (token === "{")
+            return this.parseObject(depth + 1);
+        if (token === "[")
+            return this.parseArray(depth + 1);
+        if (token === "t")
+            return this.parseLiteral("true", true);
+        if (token === "f")
+            return this.parseLiteral("false", false);
+        if (token === "n")
+            return this.parseLiteral("null", null);
+        if (token === "-" || (token !== undefined && token >= "0" && token <= "9")) {
+            return this.parseNumber();
+        }
+        throw new Error("invalid JSON value");
+    }
+    parseObject(depth) {
+        this.#offset++;
+        const value = Object.create(null);
+        const keys = new Set();
+        this.skipWhitespace();
+        if (this.consume("}"))
+            return value;
+        while (true) {
+            this.skipWhitespace();
+            if (this.input[this.#offset] !== '"')
+                throw new Error("JSON object key must be a string");
+            const key = this.parseString();
+            if (keys.has(key))
+                throw new Error("duplicate JSON object key");
+            keys.add(key);
+            this.skipWhitespace();
+            if (!this.consume(":"))
+                throw new Error("JSON object key has no value");
+            value[key] = this.parseValue(depth);
+            this.skipWhitespace();
+            if (this.consume("}"))
+                return value;
+            if (!this.consume(","))
+                throw new Error("invalid JSON object separator");
+        }
+    }
+    parseArray(depth) {
+        this.#offset++;
+        const value = [];
+        this.skipWhitespace();
+        if (this.consume("]"))
+            return value;
+        while (true) {
+            value.push(this.parseValue(depth));
+            this.skipWhitespace();
+            if (this.consume("]"))
+                return value;
+            if (!this.consume(","))
+                throw new Error("invalid JSON array separator");
+        }
+    }
+    parseString() {
+        const start = this.#offset++;
+        while (this.#offset < this.input.length) {
+            const code = this.input.charCodeAt(this.#offset++);
+            if (code === 0x22) {
+                const encoded = this.input.slice(start, this.#offset);
+                const value = JSON.parse(encoded);
+                if (typeof value !== "string")
+                    throw new Error("invalid JSON string");
+                return value;
+            }
+            if (code < 0x20)
+                throw new Error("unescaped control in JSON string");
+            if (code === 0x5c) {
+                if (this.#offset >= this.input.length)
+                    throw new Error("unterminated JSON escape");
+                if (this.input[this.#offset] === "u") {
+                    const hex = this.input.slice(this.#offset + 1, this.#offset + 5);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        throw new Error("invalid JSON unicode escape");
+                    this.#offset += 5;
+                }
+                else {
+                    if (!'"\\/bfnrt'.includes(this.input[this.#offset])) {
+                        throw new Error("invalid JSON escape");
+                    }
+                    this.#offset++;
+                }
+            }
+        }
+        throw new Error("unterminated JSON string");
+    }
+    parseNumber() {
+        // A sticky expression scans at the current offset without copying the
+        // remaining document for every number in a large deployment file.
+        JSON_NUMBER.lastIndex = this.#offset;
+        const match = JSON_NUMBER.exec(this.input);
+        if (!match)
+            throw new Error("invalid JSON number");
+        const encoded = match[0];
+        this.#offset = JSON_NUMBER.lastIndex;
+        // Keep every syntactic JSON integer distinct from fractional or exponent
+        // notation. NHP integer fields reject 1.0 and 1e0 even when Number would
+        // reduce them to the same mathematical value as 1.
+        if (!encoded.includes(".") && !/[eE]/.test(encoded)) {
+            // BigInt("-0") becomes 0n and loses the wire sign. Keep negative zero as
+            // a number so unsigned integer fields reject this noncanonical syntax.
+            if (encoded === "-0")
+                return -0;
+            return BigInt(encoded);
+        }
+        const value = Number(encoded);
+        if (!Number.isFinite(value))
+            throw new Error("JSON number is outside the finite range");
+        return value;
+    }
+    parseLiteral(literal, value) {
+        if (!this.input.startsWith(literal, this.#offset))
+            throw new Error("invalid JSON literal");
+        this.#offset += literal.length;
+        return value;
+    }
+    consume(value) {
+        if (this.input[this.#offset] !== value)
+            return false;
+        this.#offset++;
+        return true;
+    }
+}
+function isStrictJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/cjs/node.d.ts

@@ -0,0 +1,3 @@
+export { createPortalOpener, PortalBusyError, PortalConfigurationError, PortalDenyError, PortalInvalidReplyError, PortalStateError, PortalVerificationError, } from "./node/portal-opener.js";
+export type { CreatePortalOpenerOptions, PortalFetchOptions, PortalOpener, PortalRenewalFailure, PortalRequestBuilder, PortalSessionHealth, PortalStartOptions, } from "./node/portal-opener.js";
+export type { PortalDeployment, PortalDeploymentCell, PortalDeploymentIssuer, } from "./node/deployment.js";

package/dist/cjs/node.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PortalVerificationError = exports.PortalStateError = 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; } });
+Object.defineProperty(exports, "PortalConfigurationError", { enumerable: true, get: function () { return portal_opener_js_1.PortalConfigurationError; } });
+Object.defineProperty(exports, "PortalDenyError", { enumerable: true, get: function () { return portal_opener_js_1.PortalDenyError; } });
+Object.defineProperty(exports, "PortalInvalidReplyError", { enumerable: true, get: function () { return portal_opener_js_1.PortalInvalidReplyError; } });
+Object.defineProperty(exports, "PortalStateError", { enumerable: true, get: function () { return portal_opener_js_1.PortalStateError; } });
+Object.defineProperty(exports, "PortalVerificationError", { enumerable: true, get: function () { return portal_opener_js_1.PortalVerificationError; } });

package/dist/cjs/types.d.ts

@@ -229,6 +229,89 @@ export interface MintOutput {
     expires_at?: string;
     type?: ResourceType;
 }
+/** Options for `QURLClient.protectUrl`. */
+export interface ProtectUrlOptions {
+    /** Optional resource-level metadata. Max 500 chars. */
+    description?: string;
+    /** Optional resource-level tags. Max 10 items. */
+    tags?: string[];
+    /** Custom domain already verified in LayerV. */
+    customDomain?: string;
+    /** Owner-scoped handle for the resource. */
+    alias?: string;
+}
+/**
+ * Options for minting a portal (mirrors qurl-go's `PortalOption` set).
+ *
+ * Duration options accept either a duration string (`"5m"`, `"24h"`) that is
+ * passed through for the server to validate, or a number of milliseconds that
+ * gets qurl-go's client-side guardrails: whole seconds only, at least one
+ * minute for `validFor` and at least one second for `sessionDuration`.
+ * Millisecond values are serialized to the API's h/m/s duration grammar with
+ * hours as the largest unit.
+ */
+export interface CreatePortalOptions {
+    /**
+     * How long the qURL link stays valid. Omit to use the API default
+     * lifetime; prefer short lifetimes such as `"5m"`. The LayerV API remains
+     * the source of truth for account limits — there is intentionally no
+     * SDK-side maximum.
+     */
+    validFor?: string | number;
+    /** Human-readable label for the link. Max 500 chars, must not be blank. */
+    label?: string;
+    /** If `true`, the link expires after its first successful use. */
+    oneTimeUse?: boolean;
+    /**
+     * Concurrent-session limit. `0` is sent explicitly and means unlimited;
+     * omit to keep the server default.
+     */
+    maxSessions?: number;
+    /**
+     * How long access lasts after someone opens the link. Omit to use the
+     * server default; zero is rejected rather than treated as default.
+     */
+    sessionDuration?: string | number;
+}
+/**
+ * A qURL link minted for a protected resource.
+ *
+ * A portal is cryptographic, just-in-time permission for one actor to reach
+ * one private resource. `link` is the shareable qURL link; recipients open it
+ * directly and need no LayerV credentials.
+ *
+ * Mirrors `qurl.Portal` in qurl-go.
+ */
+export interface Portal {
+    /** Identifies the protected resource this link opens. */
+    resourceId: string;
+    /** The shareable qURL link. */
+    link: string;
+    /** The qURL-hosted site for this resource, when returned by the API. */
+    site?: string;
+    /** Link expiration time, when returned by the API. */
+    expiresAt?: Date;
+    /** Identifies the specific access token, when returned by the API. */
+    qurlId?: string;
+    /** Token label, when returned by the API. */
+    label?: string;
+}
+/**
+ * Result of a successful `enterPortal`: the reachable resource.
+ *
+ * Carries the reachable resource URL and the access lifetime reported by
+ * qURL (`openSeconds` is `0` when the API does not report one). `resourceId`
+ * is populated by this SDK's API-backed opener; the field does not exist on
+ * qurl-go's offline `ResourceHandle`.
+ */
+export interface ResourceHandle {
+    /** The reachable resource location. */
+    resourceUrl: string;
+    /** How long access stays open in seconds, as reported by qURL. */
+    openSeconds: number;
+    /** The LayerV resource id behind the portal, when reported. */
+    resourceId?: string;
+}
 /** Input for headless qURL resolution. */
 export interface ResolveInput {
     access_token: string;
@@ -704,23 +787,6 @@ export interface AccessCodeListOutput extends UnpaginatedOutput {
      */
     access_codes: AccessCode[];
 }
-export interface AgentBootstrapInput {
-    public_key: string;
-    agent_id?: string;
-    hostname?: string;
-    version?: string;
-}
-export interface NHPServerPeerInfo {
-    public_key_b64: string;
-    host: string;
-    port: number;
-    expire_time: number;
-}
-export interface AgentBootstrapOutput {
-    agent_id: string;
-    registered_at: string;
-    nhp_server_peer: NHPServerPeerInfo;
-}
 /** API error from the qURL service (RFC 7807). */
 export interface QURLErrorData {
     status: number;
@@ -755,7 +821,13 @@ export interface ClientOptions {
     apiKey: string;
     /** Base URL. Defaults to https://api.layerv.ai */
     baseUrl?: string;
-    /** Custom fetch implementation. */
+    /**
+     * Custom fetch implementation. Redirect-safety requires it to honor
+     * `redirect: "manual"`, accurately expose `Response.redirected`, and leave
+     * `Response.url` empty or set it to the normalized request URL when no
+     * redirect was followed. Every Response-like result must also provide a
+     * `headers` object with a WHATWG-compatible `headers.get(name)` method.
+     */
     fetch?: typeof globalThis.fetch;
     /** Maximum retry attempts for transient errors (429, 5xx). Default: 3. */
     maxRetries?: number;

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.0";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "0.3.0"; // x-release-please-version
+exports.VERSION = "0.4.0"; // x-release-please-version