@layervai/qurl 0.3.0 → 0.4.0

package/README.md

@@ -4,13 +4,34 @@
 [![CI](https://github.com/layervai/qurl-typescript/actions/workflows/ci.yml/badge.svg)](https://github.com/layervai/qurl-typescript/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/layervai/qurl-typescript)](LICENSE)
 
-TypeScript SDK for the [qURL™ API](https://docs.layerv.ai) — secure, time-limited access links for AI agents.
+**Use the LayerV [qURL™ Platform](https://docs.layerv.ai) from TypeScript: protect a
+private URL once, then mint short-lived portal links for it.**
 
 > **Quantum URL (qURL)** · The internet has a hidden layer. This is how you enter.
 
+Portal recipients do not need LayerV credentials, API keys, or SDK state. They
+open the qURL link. Credentials are only for software that protects URLs or
+creates portals.
+
 ## Why qURL?
 
-AI agents need to access protected resources — APIs, databases, internal tools — but giving them permanent credentials is a security risk. qURL creates time-limited, auditable access links that expire automatically. The SDK handles authentication, retries, pagination, and error handling so you can focus on your agent logic.
+Agents and services increasingly need to reach private MCP servers, APIs, and
+internal tools. The issue is visibility: every standing public endpoint becomes
+inventory for scanners, fingerprinting, credential attacks, and AI-assisted
+probing before a legitimate user or agent ever arrives.
+
+Opening an inbound port, running a VPN, shipping a bastion, publishing a
+Cloudflare Tunnel or ngrok URL, or passing around a long-lived key all leave
+something durable to find, scan, or steal. qURL flips that model: it is an
+invisibility primitive for authenticated access, and the private resource is
+not public inventory. A portal is **cryptographic, just-in-time permission for
+one actor to reach one private resource** — not another externally visible
+endpoint in front of the same service:
+
+- **Time-limited** — portals expire after minutes, hours, or days
+- **IP-scoped** — access is granted only to the requesting IP via NHP
+- **Auditable** — every access is logged with who, when, and from where
+- **Revocable** — kill access instantly if something goes wrong
 
 ## Installation
 
@@ -18,16 +39,200 @@ AI agents need to access protected resources — APIs, databases, internal tools
 npm install @layervai/qurl
 ```
 
-Requires Node.js 18+. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
+Requires Node.js 20+ and has **no runtime dependencies**. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
 
-## Quick Start
+## Quickstart
 
 ```typescript
 import { QURLClient } from '@layervai/qurl';
 
 const client = new QURLClient({ apiKey: 'YOUR_API_KEY' });
 
-// Create a protected link
+const resource = await client.protectUrl('https://internal.example.com/dashboard');
+const portal = await resource.createPortal({ validFor: '5m' });
+
+console.log(portal.link); // Share this link — recipients need no credentials
+```
+
+That is the core flow:
+
+| Step | Call | What you provide |
+| --- | --- | --- |
+| Protect a private URL | `client.protectUrl` | The target URL you already know |
+| Mint a short-lived access link | `resource.createPortal` | The returned resource handle |
+
+`protectUrl` is idempotent for the same account and target URL: protecting the
+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`:
+
+```typescript
+const resource = await client.connectorResource('prod-dashboard');
+const portal = await resource.createPortal({ validFor: '5m' });
+```
+
+If you persist the resource id, future calls do not need to recreate the
+handle (no API call is made until you mint):
+
+```typescript
+const resource = client.resourceById('r_demo1234567');
+const portal = await resource.createPortal({ validFor: '1h' });
+```
+
+For one-off scripts, `client.createPortalForUrl` combines the two API calls
+and returns both the portal and a reusable resource handle. The handle carries
+the resource id and target URL; use `protectUrl` when you need the full
+server-populated resource metadata:
+
+```typescript
+const { portal, resource } = await client.createPortalForUrl(
+  'https://internal.example.com/dashboard',
+  { validFor: '5m' },
+);
+```
+
+Portal options mirror qurl-go:
+
+```typescript
+const portal = await resource.createPortal({
+  validFor: 5 * 60 * 1000, // milliseconds work too
+  label: 'Alice from Acme',
+  oneTimeUse: true,
+  maxSessions: 1,
+});
+```
+
+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
+you are building a service or agent that opens received qURL links
+programmatically, `enterPortal` accepts a full link or a bare access token,
+grants network access for the caller's IP, and returns the reachable resource:
+
+```typescript
+const handle = await client.enterPortal(link);
+console.log(handle.resourceUrl); // The reachable resource location
+console.log(handle.openSeconds); // How long access stays open
+```
+
+Unlike qurl-go's offline `EnterPortal`, this SDK opens links through the
+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
+client. Use them for the qURL/resource/token management surface that has no
+portal-verb equivalent (listing, updating, revoking, quotas, webhooks, ...) or
+if you already build on them:
+
+```typescript
+// Create a protected link (portal equivalent: createPortalForUrl)
 const result = await client.create({
   target_url: 'https://api.example.com/data',
   expires_in: '24h',
@@ -35,8 +240,8 @@ const result = await client.create({
 });
 console.log(result.qurl_link);
 
-// Resolve a token (grants network access for your IP)
-const access = await client.resolve('at_...');
+// Resolve a token headlessly (portal equivalent: enterPortal)
+const access = await client.resolve('at_k8xqp9h2sj9lx7r4a');
 console.log(`Access granted to ${access.target_url} for ${access.access_grant?.expires_in}s`);
 ```
 
@@ -54,7 +259,18 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `userAgent` | No | `qurl-typescript/<version>` |
 | `debug` | No | `false` |
 
-### Methods
+### Portal methods
+
+| 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 |
+| `resourceById(id)` | Handle from a stored resource id (no API call) |
+| `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |
+
+### REST-shaped methods
 
 | Method | Description |
 |--------|-------------|
@@ -69,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 |
@@ -122,7 +337,7 @@ Non-400 errors (401, 403, 429, 5xx, and unexpected 400 body shapes) still throw
 
 ## Error Handling
 
-All API errors throw typed error subclasses, so you can catch specific failure modes:
+Match errors by type, not message text — every failure throws a typed `QURLError` subclass, and message wording is not part of the API contract:
 
 ```typescript
 import {
@@ -134,16 +349,16 @@ import {
 } from '@layervai/qurl';
 
 try {
-  await client.create({ target_url: '' });
+  await client.enterPortal('https://qurl.link/#at_k8xqp9h2sj9lx7r4a');
 } catch (err) {
-  if (err instanceof ValidationError) {
-    console.error('Invalid input:', err.invalidFields);
-  } else if (err instanceof RateLimitError) {
-    console.error(`Rate limited — retry after ${err.retryAfter}s`);
-  } else if (err instanceof AuthenticationError) {
+  if (err instanceof AuthenticationError) {
     console.error('Bad API key');
   } else if (err instanceof NotFoundError) {
-    console.error('Resource not found');
+    console.error('Portal doesn\'t exist or already expired');
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limited — retry after ${err.retryAfter}s`);
+  } else if (err instanceof ValidationError) {
+    console.error('Invalid input:', err.detail, err.invalidFields);
   } else if (err instanceof QURLError) {
     console.error(`API error [${err.code}]: ${err.detail}`);
   }
@@ -161,6 +376,13 @@ try {
 | `NetworkError` | — | Connection failure |
 | `TimeoutError` | — | Request exceeded timeout |
 
+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,
+and `"unexpected_response"` when a response is missing required fields (e.g.
+`enterPortal` failing closed on a grant with no resource URL).
+
 ## Pagination
 
 ```typescript
@@ -190,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:
@@ -210,8 +467,68 @@ await client.create(
 );
 ```
 
+The portal verbs take the same per-call options as their final argument, e.g.
+`resource.createPortal({ validFor: '5m' }, { idempotencyKey: 'mint-alice-1' })`.
+
 SDK-generated keys require `globalThis.crypto.getRandomValues`, which is available in supported Node 20+ runtimes and modern edge/browser runtimes. In constrained runtimes without Web Crypto, pass a caller-provided key with `idempotencyKey`; otherwise POST/PATCH calls throw `RuntimeError` before sending a request.
 
+## 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.
+- `protectUrl` and `createPortalForUrl` reject malformed target URLs and URLs
+  with embedded credentials (`https://user:pass@...`) before any request,
+  matching qurl-go.
+- The programmatic opener fails closed: `enterPortal` throws when access is
+  granted without a resource URL, and its error messages never echo the link.
+
 ## Versioning & breaking changes
 
 This SDK is pre-1.0; breaking changes between minor versions are possible until the API surface stabilizes. Significant changes are called out in [`CHANGELOG.md`](CHANGELOG.md) and in the corresponding GitHub release notes.