@layervai/qurl 0.3.1 → 0.4.0

package/README.md

@@ -105,6 +105,11 @@ const portal = await resource.createPortal({
 });
 ```
 
+The Node-only `@layervai/qurl/node` entry opens received qv2 links with native
+NHP 1.1 UDP. It has no relay or HTTP-resolve fallback. Connector assignment and
+registration are separate producer operations and are not part of the portal
+opener.
+
 ## Opening Portals
 
 Most recipients open qURL links directly and do not use this SDK at all. If
@@ -123,6 +128,102 @@ LayerV API: the client needs an API key with the `qurl:resolve` scope.
 `enterPortal` fails closed — if access is granted but no resource URL comes
 back, it throws instead of returning an empty handle.
 
+### Proactive native Node opener
+
+Use the Node subpath when a service receives a qv2 link and must keep one NHP
+session ready for a low-latency private request. Construct and start one opener
+for that link during setup. `start()` sends the native UDP knock and schedules
+bounded background renewal before the admission expires. Failed renewal tries
+are spread across the remaining valid grant window. `fetch()` never opens or
+renews a session, and it never sleeps. It fails if the cached admission has
+expired.
+
+```javascript
+const { createPortalOpener } = require('@layervai/qurl/node');
+
+async function uploadPrivateObject(uploadBody) {
+  const opener = createPortalOpener({
+    qurl: process.env.PRIVATE_UPLOAD_QURL,
+    transport: 'native-only',
+  });
+  try {
+    await opener.start();
+    return await opener.fetch(
+      (authenticatedTarget) => ({
+        method: 'POST',
+        headers: signUploadForExactTarget(authenticatedTarget),
+        body: uploadBody,
+      }),
+      { redirects: 'error' },
+    );
+  } finally {
+    await opener.close();
+  }
+}
+```
+
+The request builder receives a copy of the exact authenticated ACK target. The
+opener ignores mutations to that copy and sends the initial request only to the
+fixed ACK URL. It adds the private `qurl_vsession` cookie, replaces a
+caller-supplied cookie with that name, and preserves other valid cookies,
+including duplicate `Cookie` entries that Node joins with semicolons. It does
+not accept a caller URL or path. Use `redirects: 'error'` for a request
+whose signature binds its method, target, timestamp, or nonce. This mode closes
+a redirect response and does not replay the request. The default `follow` mode
+can then move within the authenticated origin. It permits at most 10 requests,
+including the initial request, and uses the standard 301/302/303 method rewrite
+rules. As in Go, a 3xx response with no `Location` header, or a 307/308 response
+whose streaming body cannot be replayed, is returned to the caller without a
+follow-up request. The caller then owns that response body and must consume or
+cancel it. Local admission expiry is checked before the first request; the
+protected service remains authoritative while a permitted redirect chain is in
+progress.
+
+`timeoutMs` bounds each resolved-address attempt, and `maxAddresses` caps the
+serial address attempts. This matches qurl-go. Every open also has a whole-open
+deadline that covers DNS and UDP: at least 15 seconds, or the configured
+per-address budget times `maxAddresses + 1` when that is larger. Pass an abort
+signal to `start()` when lifecycle code needs a shorter deadline.
+Content requests use the caller's `RequestInit.signal`; `fetch()` does not add
+an independent application-request deadline.
+
+TypeScript consumers of `@layervai/qurl/node` must provide Node and Fetch API
+declarations, for example current `@types/node`, or a configuration that includes
+the `DOM` library for Fetch types.
+
+Native opening requires public deployment trust. Set `QURL_DEPLOYMENT` to one
+strict JSON object or to a path that contains that object. The object must have
+trusted P-256 issuer keys and native cell host, UDP port 443, and X25519 public
+key entries. A configured path must be a regular file no larger than 1 MiB. The
+SDK loads and validates this value once when it constructs the opener. It does
+not perform discovery and it fails before DNS if the verified link names an
+unknown cell.
+
+Use `opener.health()` for the local `idle`, `starting`, `healthy`, `renewing`,
+`degraded`, `expired`, or `closed` state. A degraded state includes a typed
+renewal failure class but no raw session capability. After bounded background
+retries stop, `start()` makes one explicit recovery attempt and refreshes the
+health result. If that explicit attempt fails while the prior grant is still
+usable, the opener re-arms its bounded background attempts after it returns the
+error. This does not put an open or sleep on the `fetch()` path. Stop and await
+in-flight content requests before you call `await opener.close()` during
+shutdown. Close cancels and waits for an active NHP exchange, then wipes the
+mutable private-key, visitor-secret, and session-token buffers. JavaScript can
+create immutable string copies during JSON and HTTP processing, so the SDK
+cannot promise full memory zeroization before garbage collection. Never log the
+qURL, ACK body, request cookies, or request headers.
+
+A cold `start()` failure leaves health at `idle`. Catch `PortalBusyError` for an
+authenticated COOKIE busy response and `PortalInvalidReplyError` for a malformed
+authenticated reply. The thrown typed error is the cold-start diagnostic.
+
+Local qv2 verification checks the signed bytes, trust, and clock-free claim
+ordering. As in the Go SDK, it does not compare `nbf` or `exp` with the local
+clock. The authenticated NHP open is the authoritative live validity check.
+The opener also follows the Go NHP 1.1 COOKIE rule: an authenticated COOKIE is
+a busy result and does not use ACK counter correlation or local clock skew
+checks. Replaying it can only force another busy result; it cannot grant access.
+
 ## REST-Shaped API (Compatibility)
 
 The original REST-shaped methods remain fully supported and share the same
@@ -184,7 +285,6 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `mintLink(id, input?)` | Mint a new access link |
 | `resolve(input)` | Resolve token + grant network access |
 | `getQuota()` | Get quota/usage info |
-| `bootstrapAgent(input)` | Bootstrap a qURL Connector agent |
 | `listResources(input?)` / `listAllResources(input?)` / `createResource(input)` / `getResource(id)` | Resource management |
 | `updateResource(id, input)` / `deleteResource(id)` | Update or revoke resources |
 | `createQurlForResource(id, input?)` | Mint a qURL for an existing resource |
@@ -312,15 +412,50 @@ const clientWithLogger = new QURLClient({
 
 ## Retry Behavior
 
-The client automatically retries failed requests with exponential backoff:
-
-- **GET/DELETE**: Retries on 429, 502, 503, 504
-- **POST/PATCH**: Retries status responses only on 429
-- **Network errors**: Always retried; POST/PATCH requests send an `Idempotency-Key` on the first attempt and reuse it on retries
-- **`Retry-After` header**: Honored on 429 and 503 responses (RFC 7231 §7.1.3). Currently the SDK only parses **delta-seconds** values (e.g. `Retry-After: 30`); HTTP-date values (`Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`) silently fall back to exponential backoff. Tracked in [#61](https://github.com/layervai/qurl-typescript/issues/61).
+The client retries only requests whose replay contract is explicit:
+
+- **GET**: Retries on 429, 502, 503, 504 and transport failures, including a
+  dropped response body after successful headers arrive
+- **POST/PATCH**: Retries complete status responses only on 429. A transport
+  failure while reading a response body is not replayed because the mutation
+  may have applied.
+- **POST/PATCH fetch failures**: Retried with the `Idempotency-Key` generated on
+  the first attempt when no response is available
+- **DELETE**: Never replayed automatically, including on 429. A transport
+  failure after dispatch makes the mutation outcome unknown, and the HTTP verb
+  alone cannot prove a replay safe. Reconcile resource state before you issue
+  a deliberate retry. This matches qurl-go's explicit-caller-retry model.
+- **`Retry-After` header**: Preserved on 429 and 503 responses, including when
+  a mid-body transport failure produces a status-derived error (RFC 7231
+  §7.1.3), and honored by automatic GET retries. Currently the SDK only parses
+  **delta-seconds** values (e.g.
+  `Retry-After: 30`); HTTP-date values (`Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`)
+  silently fall back to exponential backoff. Tracked in
+  [#61](https://github.com/layervai/qurl-typescript/issues/61).
+- **Response failures**: Redirects, oversized successful bodies, and malformed
+  UTF-8 successful bodies are not retried. Retryable error statuses remain
+  retryable when an intermediary returns HTML, an empty body, malformed UTF-8,
+  or another complete non-envelope error response. A mid-stream transport
+  failure is retried for a successful GET or a GET with a retryable status.
+  A hard 4xx GET is not retried. An independent `AbortError` or `TimeoutError`
+  from an injected fetch, or while reading a successful response body, is a
+  non-retried `NetworkError`. After non-success headers arrive, the SDK
+  preserves the status-derived error class and attaches the independent
+  failure as its cause without retrying it. Only the SDK's timeout signal
+  produces a `TimeoutError`. Mutations require reconciliation.
+
+All documented no-content DELETE operations require exactly HTTP 204 with an
+empty response body. Alternate success statuses or response bytes fail closed
+as `unexpected_response` contract errors whose `.status` preserves the
+observed HTTP status. The delete may already have applied; reconcile resource
+state before retrying.
 
 Configure with `maxRetries` (default: 3). Set to `0` to disable.
 
+When DELETE returns `RateLimitError`, use `retryAfter` for scheduling but
+reconcile current resource state before issuing a deliberate retry; the SDK
+does not assume the rejected response proves the mutation never ran.
+
 > **Worst-case latency**: `timeout` is enforced per *attempt*, not for the whole request. Total worst-case latency is roughly `timeout × (maxRetries + 1) + sum(retry delays)`. Operators tuning `timeout` should account for this when sizing health-check budgets.
 
 For POST/PATCH requests, the SDK generates a UUIDv7 `Idempotency-Key` once per logical call and reuses it across SDK-managed retries, so the API can return the original result instead of creating duplicate resources. If your application catches an error and calls the SDK again, pass a stable override so the new call deduplicates with the first one. Caller-provided keys must be non-empty printable ASCII strings of at most 256 characters and must not start or end with spaces. Use a unique key for each logical operation; reusing one key for a different request can return the first cached response. To tie retries to your own upstream job or request ID, pass a per-call override:
@@ -340,6 +475,51 @@ SDK-generated keys require `globalThis.crypto.getRandomValues`, which is availab
 ## Security Notes
 
 - Treat API keys and qURL links like credentials. Do not log them.
+- SDK API requests use manual redirect handling. Redirect-capable HTTP statuses
+  (300, 301, 302, 303, 305, 307, 308), filtered `opaqueredirect` responses in
+  browsers and Node native fetch, and responses a custom fetch reports as
+  already redirected are rejected as a typed `QURLError`
+  (`code: "unexpected_response"`) without requesting the `Location` target.
+  This prevents forwarding `Authorization` and
+  `Idempotency-Key` when the fetch implementation honors `redirect: "manual"`
+  and accurately exposes `Response.redirected`. A shim must also leave
+  `Response.url` empty or report the normalized request URL when it did not
+  follow a redirect. Every Response-like shim must provide `headers.get(name)`.
+  A non-empty invalid `Response.url` fails closed with an SDK-authored error
+  that names this shim requirement but does not reflect the invalid value. A
+  non-redirecting 304 is handled as an ordinary unsuccessful API response
+  rather than mislabeled as a redirect.
+- API success and error bodies are limited to **1 MiB (1,048,576 bytes)**,
+  matching qurl-go's security posture. The SDK checks `Content-Length` when
+  present and independently counts streamed bytes, so missing or inaccurate
+  headers cannot bypass the limit. Bodies exactly at the limit are accepted.
+  This fixed security limit has no override. Callers must request a smaller
+  page, and the SDKs must not independently widen the limit.
+  A maximum-size list page can exceed the cap after JSON escaping; request a
+  smaller page if a list call reports the body-limit error. For resumable list
+  reads, use the page method, save each successful `next_cursor`, and resume
+  from that cursor with a smaller `limit`. A shared configurable-cap decision
+  is tracked in [#249](https://github.com/layervai/qurl-typescript/issues/249).
+  Standards-compliant fetch implementations are bounded while streaming;
+  custom Response-like shims that omit `body` are validated after their
+  `text()`/`json()` result has already been materialized by that shim.
+  Oversized bodies fail with a typed error before JSON decoding while
+  preserving the observed status-derived error class and `Retry-After`.
+  Transient error statuses retain the normal retry policy for GET and
+  idempotency-key-backed mutations; oversized successful responses and DELETE
+  responses are not retried.
+  Successful JSON bodies with malformed UTF-8 are rejected without replay.
+  Server-provided error title/detail snippets and `invalidFields` keys/values
+  have controls and bidirectional formatting characters removed, are
+  normalized to one line, and are capped at 512 UTF-8 bytes. Machine-readable
+  error codes, RFC 7807 type/instance values, and request IDs are kept only
+  when they need no normalization and fit the same limit. At most 100
+  `invalidFields` entries are retained, and each retained
+  `invalidFields` or debug `body_keys` collection has an 8 KiB UTF-8 budget.
+  Redirect/body-limit contract-error details do not include `Location` values
+  or response-body snippets. Standard request debug logging includes the request
+  URL, so do not place credentials in identifiers or enable debug output in a
+  sensitive logging environment.
 - Prefer short portal lifetimes such as `validFor: '5m'`.
 - Do not ask portal recipients to handle credentials. Recipients only need
   the link.

package/dist/cjs/client.d.ts

@@ -1,4 +1,12 @@
-import type { AccessCodeListOutput, AgentBootstrapInput, AgentBootstrapOutput, ApiKey, ApiKeyListOutput, BillingInvoiceListOutput, BatchCreateInput, BatchCreateOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationListOutput, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, Domain, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListInput, ListOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListWebhookDeliveriesInput, ListWebhooksInput, MintInput, MintOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, RequestOptions, ResolveInput, ResolveOutput, SessionListOutput, SessionTerminateOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCurrentPeriod, UsageDaily, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventTypeInfo, WebhookListOutput, WebhookWithSecret } from "./types.js";
+import type { AccessCodeListOutput, ApiKey, ApiKeyListOutput, BillingInvoiceListOutput, BatchCreateInput, BatchCreateOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationListOutput, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, Domain, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListInput, ListOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListWebhookDeliveriesInput, ListWebhooksInput, MintInput, MintOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, RequestOptions, ResolveInput, ResolveOutput, SessionListOutput, SessionTerminateOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCurrentPeriod, UsageDaily, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventTypeInfo, WebhookListOutput, WebhookWithSecret } from "./types.js";
+/**
+ * Shape of qurl-go's offline signed-fragment links: three or more
+ * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
+ * Detected only to give those links a precise error in extractAccessToken.
+ *
+ * @internal Exported for in-package tests; not re-exported from index.ts.
+ */
+export declare const SIGNED_FRAGMENT_RE: RegExp;
 /** qURL API client. */
 export declare class QURLClient {
     private readonly baseUrl;
@@ -307,8 +315,6 @@ export declare class QURLClient {
     resolve(input: ResolveInput | string, options?: RequestOptions): Promise<ResolveOutput>;
     /** Get quota and usage information. */
     getQuota(): Promise<Quota>;
-    /** Bootstrap a LayerV qURL Connector agent. */
-    bootstrapAgent(input: AgentBootstrapInput, options?: RequestOptions): Promise<AgentBootstrapOutput>;
     /** List resources from the `/v1/resources` API. */
     listResources(input?: ResourceListInput): Promise<ResourceListOutput>;
     /**
@@ -349,13 +355,7 @@ export declare class QURLClient {
      * this page and emits a debug log rather than pretending it fetched all pages.
      */
     listResourceSessions(id: string): Promise<SessionListOutput>;
-    /**
-     * Terminate all active sessions for a resource.
-     *
-     * The returned count is best-effort under retries: if the first DELETE
-     * succeeds server-side but the response is lost, a retried request may
-     * return `0` because there are no sessions left to terminate.
-     */
+    /** Terminate all active sessions for a resource and return the server count. */
     terminateAllResourceSessions(id: string): Promise<SessionTerminateOutput>;
     /** Terminate a specific resource session. */
     terminateResourceSession(id: string, sessionId: string): Promise<void>;
@@ -468,6 +468,12 @@ export declare class QURLClient {
     /** Revoke an access code. */
     revokeAccessCode(id: string): Promise<void>;
     private request;
+    /**
+     * Require the service's exact 204 response with no response bytes exposed by
+     * Fetch. A standards-compliant Fetch implementation discards any forbidden
+     * wire body on 204, so the SDK cannot detect bytes that Fetch did not expose.
+     */
+    private requestNoContent;
     /**
      * Issue an HTTP request and parse the JSON response.
      *
@@ -495,6 +501,7 @@ export declare class QURLClient {
      */
     private retryDelay;
     private classifyFetchError;
+    private classifyResponseReadError;
 }
 /**
  * A LayerV-protected resource, bound to the client that produced it.