@layervai/qurl 0.4.0 → 0.6.0

package/README.md

@@ -39,7 +39,9 @@ endpoint in front of the same service:
 npm install @layervai/qurl
 ```
 
-Requires Node.js 20+ and has **no runtime dependencies**. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
+Requires Node.js 22.12+ and has **no runtime dependencies**. Both
+`import { QURLClient } from '@layervai/qurl'` (ESM) and
+`const { QURLClient } = require('@layervai/qurl')` (CJS) work.
 
 ## Quickstart
 
@@ -66,14 +68,60 @@ same URL again returns the existing resource. `validFor` accepts a duration
 string (`'5m'`, `'24h'`) or a number of milliseconds (whole seconds, at least
 one minute); prefer short portal lifetimes.
 
-If qURL Connector already protects the service, use the connector id instead
-of calling `protectUrl`:
+If qURL Connector protects the service, address its management-plane resource
+by immutable slug instead of calling `protectUrl`:
 
 ```typescript
-const resource = await client.connectorResource('prod-dashboard');
-const portal = await resource.createPortal({ validFor: '5m' });
+const { resource, foundExisting } = await client.ensureConnectorResource(
+  'prod-dashboard',
+  { idempotencyKey: 'connector-bootstrap-prod-dashboard' },
+);
+console.log(foundExisting ? 'Using existing connector resource' : 'Created connector resource');
+const portal = await resource.createPortal({
+  validFor: '5m',
+  targetPath: '/api/detect/eib_example',
+});
 ```
 
+`targetPath` is available only when minting for an existing resource. The SDK
+checks the non-empty 2048-byte boundary; the API remains authoritative for the
+path grammar and the tunnel-only resource gate. `createPortalForUrl` rejects
+this option because it creates a URL resource.
+
+`resource.resourceId`, `resource.connectorRoutingId`, and
+`resource.knockResourceId` are three distinct server-issued values for public
+identity, reverse routing, and NHP admission. Consume each verbatim; never
+derive or substitute one for another. Use `getConnectorResource(resourceId)`
+or `getConnectorResourceBySlug(slug)` for read-only lookup and
+`deleteConnectorResource(resourceId)` to revoke it. This replaces the old
+alias-based `connectorResource(connectorId)` method.
+`ConnectorResource` instances cannot be constructed directly; the client
+returns them only after validating the complete response contract.
+
+`ensureConnectorResource` and `deleteConnectorResource` throw
+`ConnectorResourceOutcomeUnknownError` when a dispatched mutation may have
+committed but its response cannot prove the result. Reconcile by immutable slug
+or resource ID before deciding whether to retry. The wrapper deliberately uses
+`status: 0`; the original typed error is available as `cause`, including its
+observed HTTP status.
+
+Connector lifecycle calls make one HTTP attempt. The SDK does not pace or
+replay them; the caller controls any retry after it reconciles state.
+
+`ensureConnectorResource` does not generate an idempotency key because the slug
+operation is already idempotent. If you supply an `idempotencyKey`, the SDK
+forwards it, and you must reuse it on any deliberate retry. A 409
+`bootstrap_key_consumed` response is outcome-unknown because resource binding
+can finish before bootstrap-key consumption fails. The original bootstrap key
+is terminal: do not retry it. Obtain a new bootstrap key and use normal
+owner-authenticated lookup by immutable slug to reconcile the resource first.
+
+The API does not apply idempotency replay to DELETE, so after an outcome-unknown
+`deleteConnectorResource` call, reconcile by resource ID before issuing a
+deliberate retry. A valid exact-201 resource missing only `meta.found_existing`
+is known to have selected that row but still fails as an unwrapped
+`unexpected_response` because required ensure metadata is absent.
+
 If you persist the resource id, future calls do not need to recreate the
 handle (no API call is made until you mint):
 
@@ -102,11 +150,15 @@ const portal = await resource.createPortal({
   label: 'Alice from Acme',
   oneTimeUse: true,
   maxSessions: 1,
+  targetPath: '/api/detect/eib_example',
 });
 ```
 
+`createPortal` sends `{}` when no options are set because the service requires
+a JSON object at the wire level.
+
 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
+NHP 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.
 
@@ -133,10 +185,15 @@ back, it throws instead of returning an empty handle.
 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.
+background renewal before the admission expires. A transient renewal failure
+retries after 500 ms, then 1 second, then at most every 2 seconds while the old
+admission remains valid. `fetch()` never opens or renews a session, and it never
+sleeps. It fails if the cached admission has expired.
+
+Renewal waits at least 5 seconds after a successful open. If a server grants a
+session that expires before that safe renewal point, the grant expires without
+a background attempt and `start()` is the explicit recovery path. Production
+admissions should be longer than this minimum gap.
 
 ```javascript
 const { createPortalOpener } = require('@layervai/qurl/node');
@@ -144,7 +201,6 @@ 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();
@@ -162,65 +218,120 @@ async function uploadPrivateObject(uploadBody) {
 }
 ```
 
-The request builder receives a copy of the exact authenticated ACK target. The
+For a service whose ACK target is a base path, append only trusted raw path
+segments with `fetchDescendant()`. The opener rejects empty, dot, and delimiter
+segments and escapes each accepted segment before it sends the request:
+
+```javascript
+const response = await opener.fetchDescendant(
+  ['eib_example'],
+  (authenticatedTarget) => ({ method: 'POST' }),
+  { redirects: 'error' },
+);
+```
+
+The request builder receives a copy of the selected authenticated 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.
+fixed ACK URL or the validated descendant. A descendant call accepts raw path
+segments, not a URL or path string. It preserves the ACK target query and
+escapes each segment separately. 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, and it rejects a caller-supplied `Host` header
+so Fetch derives the authority from the pinned target. Both `fetch()` and
+`fetchDescendant()` use only the cached NHP 1.1 admission. Use
+`redirects: 'error'` to keep a descendant request at its initial target. The
+default `follow` mode can move outside that path subtree, but only within the
+authenticated origin. Also 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. Follow mode 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.
+
+When `fetch()` rejects before it sends a direct `RequestInit`, it releases a
+caller-owned streaming body. It cancels a web `ReadableStream`, destroys a Node
+`Readable`, or closes another iterator when that body supports the operation. A
+request builder remains lazy and is not called until a grant is ready.
+
+Each open has a whole-operation deadline that covers DNS and UDP.
+`openTimeoutMs` sets this ceiling; the default is 15 seconds and the maximum is
+60 seconds. Native DNS or address attempts can fail before this ceiling, so a
+larger value does not extend their internal timeouts. A renewal also stops at
+the old grant's expiry. Pass an abort signal to `start()` when lifecycle code
+needs a shorter deadline. Concurrent `start()` calls share one attempt. The
+first caller's signal owns that attempt, so its abort fails all waiters but does
+not count as an open failure in health. A cold cancellation restores `new`; a
+recovery cancellation preserves its prior `degraded` health. A later waiter's
+abort stops only that wait.
 Content requests use the caller's `RequestInit.signal`; `fetch()` does not add
-an independent application-request deadline.
+an independent application-request deadline. The signal stays active while the
+returned response body is read. Set the opener's optional `fetch` when the
+protected request must use a custom Fetch implementation. Native NHP opening
+never uses this function. The custom function receives the `qurl_vsession`
+bearer cookie and is inside the credential boundary. It must implement standard
+Fetch signal behavior and honor `redirect: 'manual'`. If it needs a receiver,
+pass it already bound; the SDK invokes it with the standard global Fetch
+receiver. An unfollowed synthetic response can leave `Response.url` empty.
+Otherwise, it must report
+`Response.url` and `Response.redirected` accurately. It must not log or forward
+protected request headers.
 
 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.
+the `DOM` library for Fetch types. The native opener requires Node 22.12 or later.
+This floor ensures that composite request signals are reclaimed on long-lived
+openers.
 
 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.
+key entries. A configured path must be a regular file no larger than 1 MiB.
+Construction does no I/O. `start()` resolves and validates the deployment, and
+the first successful open pins that resolved trust for renewal and recovery.
+The opener does not perform discovery. It fails before DNS if the verified link
+names an unknown cell.
+
+Use `opener.health()` for the local `new`, `starting`, `ready`, `degraded`, or
+`closed` state. It reports absolute expiry, renewal, and last-success times, a
+secret-free failure class, and the number of consecutive unsuccessful open
+attempts. A renewal window can contain more than one such attempt. The
+`starting` state is only for the first cold open; an explicit recovery from a
+failure reports `degraded` until it succeeds. Date fields describe the most
+recent successful grant, so use `ready` as the authority for current usability.
+A transient renewal failure keeps the state `ready` while the prior admission
+is usable. A changed authenticated target is not retried. It keeps the prior
+admission until expiry. During that time, `start()` remains idempotent because
+the old admission is still usable; `health().lastFailureClass` reports the
+target change. After expiry, an explicit `start()` attempts recovery. If the
+target change is intentional and permanent, create a new opener for the new
+qURL; the old opener stays bound to its first authenticated target. Other
+failures retry through the remaining admission window. This does not put an
+open or sleep on the `fetch()` path.
+
+Close cancels and waits for an active NHP open, then wipes the mutable
+private-key, visitor-secret, and session-token buffers. Close also aborts a
+protected request and its returned response body, and prevents another redirect
+leg from starting. JavaScript can create immutable string copies during JSON
+and HTTP processing, so the SDK cannot promise full memory zeroization before garbage
+collection. The opener retains the immutable qURL string until close so it can
+verify each renewal. Never log the qURL, ACK body, request cookies, or request
+headers.
+
+A cold `start()` failure leaves health at `degraded`. Catch `PortalBusyError`
+for an authenticated COOKIE busy response and `PortalInvalidReplyError` for a
+malformed authenticated reply. An open deadline throws `PortalOpenTimeoutError`.
+The thrown typed error is the cold-start
+diagnostic; health does not expose its message or secret values.
 
 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
+The opener also follows the Go NHP 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.
 
@@ -264,9 +375,11 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | Method | Description |
 |--------|-------------|
 | `protectUrl(targetUrl, opts?)` | Protect a private URL → portal-minting `ProtectedResource` handle |
-| `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link (`Portal`) |
-| `createPortalForUrl(targetUrl, opts?)` | Protect + mint in one API call → `{ portal, resource }` |
-| `connectorResource(connectorId)` | Handle for a service qURL Connector already protects |
+| `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link; existing resources can set `targetPath` |
+| `createPortalForUrl(targetUrl, opts?)` | Protect + mint a URL resource; rejects `targetPath` |
+| `ensureConnectorResource(slug, requestOptions?)` | Find or create an active Connector resource by immutable slug |
+| `getConnectorResource(resourceId)` / `getConnectorResourceBySlug(slug)` | Load a validated Connector resource by immutable identity |
+| `deleteConnectorResource(resourceId)` | Revoke a Connector resource by immutable public resource ID |
 | `resourceById(id)` | Handle from a stored resource id (no API call) |
 | `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |
 
@@ -379,7 +492,7 @@ try {
 Client-detected failures use `status: 0` with a discriminating `code`:
 `"client_validation"` for bad input caught before a request, and — on the
 portal surface — `"resource_not_found"` / `"ambiguous_resource"` when
-`connectorResource` cannot resolve a connector id to exactly one resource,
+`getConnectorResourceBySlug` cannot resolve a slug to exactly one resource,
 and `"unexpected_response"` when a response is missing required fields (e.g.
 `enterPortal` failing closed on a grant with no resource URL).
 

package/dist/cjs/client.d.ts

@@ -92,23 +92,19 @@ export declare class QURLClient {
      * need the full resource details.
      */
     resourceById(id: string): ProtectedResource;
+    /** Find or create the active qURL Connector resource for an immutable slug. */
+    ensureConnectorResource(slug: string, requestOptions?: RequestOptions): Promise<EnsureConnectorResourceResult>;
+    /** Fetch a qURL Connector resource by its immutable public resource ID. */
+    getConnectorResource(resourceId: string): Promise<ConnectorResource>;
+    /** Fetch the single active qURL Connector resource for an immutable slug. */
+    getConnectorResourceBySlug(slug: string): Promise<ConnectorResource>;
     /**
-     * Return the resource qURL Connector created for `connectorId`.
+     * Revoke a qURL Connector resource by immutable public resource ID.
      *
-     * Use when qURL Connector already protects the service — do not call
-     * {@link protectUrl} again for the same service. The connector id is the
-     * resource slug LayerV stores for that connector; the LayerV API performs
-     * the slug lookup, and the SDK confirms the returned alias matches
-     * `connectorId` before binding the handle (qurl-go:
-     * `Client.ConnectorResource`).
-     *
-     * Throws {@link NotFoundError} (`status: 0`, `code: "resource_not_found"`)
-     * when no resource exists for the connector id, {@link QURLError}
-     * (`code: "ambiguous_resource"`) when the lookup returns more than one
-     * resource, and {@link ValidationError} (`code: "unexpected_response"`)
-     * when the returned resource's alias is missing or does not match.
+     * The API does not apply Idempotency-Key replay to DELETE. After an
+     * outcome-unknown failure, reconcile by ID before issuing a deliberate retry.
      */
-    connectorResource(connectorId: string): Promise<ProtectedResource>;
+    deleteConnectorResource(resourceId: string): Promise<void>;
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
      *
@@ -116,14 +112,15 @@ export declare class QURLClient {
      * reach one private resource. Recipients open `portal.link` directly and
      * need no LayerV credentials. Prefer short lifetimes such as
      * `{ validFor: "5m" }`. Accepts a {@link ProtectedResource} handle or a
-     * resource id (`r_` prefix). REST-shaped equivalents: {@link mintLink} /
+     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
      * number of milliseconds with qurl-go's client-side guardrails: whole
      * seconds only, at least one minute for `validFor` and one second for
      * `sessionDuration`. `maxSessions: 0` is sent explicitly and means
-     * unlimited; blank labels are rejected.
+     * unlimited; blank labels are rejected. `targetPath` is valid only for an
+     * existing resource. The API owns its full grammar and tunnel-only gate.
      */
     createPortal(resource: ProtectedResource | string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
     /**
@@ -135,7 +132,9 @@ export declare class QURLClient {
      * {@link protectUrl} when you need the full server-populated resource
      * metadata. Portal options match {@link createPortal}; `targetUrl` gets
      * the same malformed-URL and embedded-credentials rejection as
-     * {@link protectUrl}. REST-shaped equivalent: {@link create}.
+     * {@link protectUrl}. `targetPath` is rejected because this call creates a
+     * URL resource instead of addressing an existing resource. REST-shaped
+     * equivalent: {@link create}.
      */
     createPortalForUrl(targetUrl: string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<{
         portal: Portal;
@@ -506,14 +505,13 @@ export declare class QURLClient {
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl},
- * {@link QURLClient.connectorResource}, or {@link QURLClient.resourceById} —
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceById} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
 export declare class ProtectedResource {
     #private;
-    /** The LayerV resource id (`r_` prefix). */
+    /** The LayerV public resource ID. */
     readonly id: string;
     /** The private URL protected by this resource, when known. */
     readonly targetUrl?: string;
@@ -537,3 +535,31 @@ export declare class ProtectedResource {
      */
     createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
 }
+/** Result of idempotently ensuring a qURL Connector resource. */
+export interface EnsureConnectorResourceResult {
+    resource: ConnectorResource;
+    foundExisting: boolean;
+}
+declare const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN: unique symbol;
+/**
+ * A validated qURL Connector resource bound to the client that loaded it.
+ *
+ * Resource identity, reverse-routing identity, and NHP admission identity are
+ * distinct server-issued values. Callers must consume each field verbatim and
+ * must never derive one from another.
+ */
+export declare class ConnectorResource {
+    #private;
+    readonly resourceId: string;
+    /** Producer-supplied CRID carried verbatim; verify it against a trusted key before trust. */
+    readonly crid?: string;
+    readonly connectorRoutingId: string;
+    readonly knockResourceId: string;
+    readonly slug: string;
+    readonly alias?: string;
+    /** @internal Instances are returned by QURLClient after wire validation. */
+    constructor(client: QURLClient, details: Resource, validationToken: typeof CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
+    /** Mint a short-lived portal for this Connector resource. */
+    createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
+}
+export {};