@layervai/qurl 0.6.0 → 2.0.0

package/README.md

@@ -88,12 +88,15 @@ 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)`
+`resource.crid` is the required management identifier. Connector lookup, delete,
+and portal minting use it with no public-key or private-ID fallback. The SDK
+checks that the returned public key matches the CRID.
+
+`resource.resourcePublicKey`, `resource.connectorRoutingId`, and
+`resource.knockResourceId` are three distinct server-issued values for verification, reverse routing, and NHP admission. Consume each verbatim; never
+derive or substitute one for another. Use `getConnectorResource(crid)`
 or `getConnectorResourceBySlug(slug)` for read-only lookup and
-`deleteConnectorResource(resourceId)` to revoke it. This replaces the old
+`deleteConnectorResource(crid)` 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.
@@ -101,7 +104,7 @@ 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
+or CRID before deciding whether to retry. The wrapper deliberately uses
 `status: 0`; the original typed error is available as `cause`, including its
 observed HTTP status.
 
@@ -117,17 +120,20 @@ 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
+`deleteConnectorResource` call, reconcile by CRID 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
+If you persist the CRID, 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' });
+async function createPortalForStoredResource(storedCrid: string) {
+  // Pass the CRID previously returned by the API.
+  const resource = client.resourceByCrid(storedCrid);
+  return resource.createPortal({ validFor: '1h' });
+}
 ```
 
 For one-off scripts, `client.createPortalForUrl` combines the two API calls
@@ -162,6 +168,174 @@ 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.
 
+If you already hold a CRID, mint a fresh share link directly:
+
+```typescript
+const share = await client.shareResource(crid, { ttlSeconds: 300 });
+// Optional: verify the response CRID against DER SPKI bytes you already trust
+// before the secret leaves this process.
+await share.verifyCrid(resourcePublicKeyDer);
+await deliverToRecipient(share.link); // Secret; returned once and not retrievable
+console.log(share.qurlId); // Safe handle for revoking only this link later
+```
+
+`shareResource` returns the current share-safe `#qv2t1...` link. Recipients
+open that URL in the qURL browser flow. For native TypeScript opening, pass
+`share.link` to `createPortalOpener` from `@layervai/qurl/node` with trusted
+`QURL_DEPLOYMENT` configuration and `expectedCRID: advertisedCRID`.
+Obtain `advertisedCRID` independently of the response carrying the link.
+The opener verifies the issuer signature and CRID/key binding before each
+native access request, including renewals. Empty, malformed, unsupported,
+and mismatched CRIDs fail closed. Omitting the option retains link-only access.
+This verifies resource identity, not content or current revocation state.
+The access-binding check accepts only locally registered versions and their
+registered digest widths, matching the Go SDK and browser agent. Upgrade the
+SDK when a new version is activated. This is stricter than the forwarding
+and supplied-key helper below. See the native opener example below.
+`verifyCrid` does not open the link or make a network request.
+
+`verifyCrid` verifies that the response CRID derives from the trusted resource
+key; it does not independently bind the secret link fragment to that key.
+It intentionally follows qurl-go's environment-agnostic key-match rule: CRID
+version zero is rejected as reserved, while every other structurally valid
+version is accepted and environment classification is not part of key-to-digest
+verification. It compares all 32 digest bytes for a full CRID and all 24 for
+a truncated CRID; the response determines the digest width. CRIDs use their canonical lowercase base32 spelling; uppercase or
+mixed-case spellings fail closed. Binary inputs of any length are hashed;
+`invalid_crid_key` is reserved for non-binary or unreadable (detached) runtime
+values, and a readable binary key that does not match reports `crid_mismatch`.
+Use `error instanceof CRIDVerificationError` (or `error.status === 0`) to
+distinguish these local verification failures from a server error that happens
+to use the same problem code.
+`qurlId` and `singleUse` are undefined when omitted by the service.
+`ShareLink` keeps `.link` directly readable but redacts it from JSON, Node
+inspection, and object spread to reduce accidental credential logging. Read
+`.link` directly before delivery; do not spread or clone a `ShareLink`, because
+those operations deliberately omit the credential. Browser developer consoles
+can still display non-enumerable properties, so do not log the object there.
+The constructor snapshots a caller-provided expiry, and the `ShareLink`
+properties are frozen. Each `expiresAt` read returns a defensive `Date` copy;
+changing that copy does not change the share metadata.
+
+Omitting `ttlSeconds` matches qurl-go's zero-value behavior and requests the
+platform default. TypeScript additionally rejects an explicit zero so a
+computed countdown cannot silently become a longer-lived default credential.
+A response can report `expiresInSeconds: 0`; do not reuse that value as a
+request TTL. Expiry parsing uses the SDK's shared API date parser.
+
+The service chooses single-use policy; this matches the Go SDK options.
+
+qURL Connector assignment and registration use native UDP through
+`qurl-connector` and `qurl-go`. This package does not expose an HTTP enrollment API.
+Like the Go SDK, credential minting uses HTTPS and token consumption uses
+native UDP. The Go SDK currently exposes minting through its restricted
+`RegisteredAgentResourceHTTPDoer` bridge; this SDK uses `createApiKey`.
+The service controls which credential kinds each caller can mint.
+It can mint the one-shot credential consumed by that native enrollment flow:
+
+```typescript
+const enrollment = await client.createApiKey({
+  kind: 'enrollment_token',
+  name: 'prod-dashboard enrollment',
+  target: 'connector',
+  claims: [{ type: 'connector', id: 'prod-dashboard' }],
+  expires_in: '15m',
+});
+if (!enrollment.api_key) throw new Error('Enrollment response omitted its one-time token');
+await deliverEnrollmentTokenSecurely(enrollment.api_key);
+```
+
+Durable `api_key` credentials require explicit scopes and do not accept
+`expires_in`; enrollment tokens derive their scopes from `target`/`claims` and
+expire within 24 hours. A connector claim's `id` is its immutable connector
+slug. Request enums are validated against the current service contract;
+response types remain additive for forward-compatible reads, and new request
+enum values require a matching SDK release. Use
+`isApiKeyRequestScope(scope)` to validate response scopes before writing them
+back. Reject unknown scopes; do not filter them out, which can remove permissions.
+When changing only a name, omit `scopes` from `updateApiKey`.
+
+```typescript
+import { isApiKeyRequestScope } from '@layervai/qurl';
+
+const scopes = key.scopes;
+if (!scopes?.length || !scopes.every(isApiKeyRequestScope)) {
+  throw new Error('Cannot reuse these scopes; check the current SDK contract');
+}
+await client.updateApiKey(keyId, { scopes });
+```
+
+This credential surface requires the kind-first qurl-service contract at or
+after commit `047cf31e1cdf545e3060e0f9294d738a19fb997b`.
+
+## Delegated qURL batches
+
+Services with a delegated mint capability can create up to 100 ordered grants
+without an API call per recipient:
+
+```typescript
+import { DelegatedBatchOutcomeUnknownError, QURLClient } from '@layervai/qurl';
+
+const client = new QURLClient({ apiKey: process.env.QURL_API_KEY! });
+const key = crypto.randomUUID();
+const mintCapability = process.env.QURL_MINT_CAPABILITY!;
+const recipients = [{ name: 'Alice' }];
+
+const accepted = await client
+  .createDelegatedQurlBatch(
+    {
+      mint_capability: mintCapability,
+      grants: recipients.map((recipient) => ({ label: recipient.name, expires_in: '1h' })),
+    },
+    { idempotencyKey: key },
+  )
+  .catch((error: unknown) => {
+    if (error instanceof DelegatedBatchOutcomeUnknownError && error.batchId) {
+      console.error('Poll the accepted batch before retrying', { batchId: error.batchId });
+    }
+    // A deliberate retry must reuse this key and exact body.
+    throw error;
+  });
+
+let etag = accepted.etag;
+let retryAfter = accepted.retry_after;
+let state;
+const deadline = Date.now() + 60_000;
+for (let polls = 0; polls < 30 && Date.now() < deadline; polls++) {
+  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+  state = await client.getDelegatedQurlBatch(accepted.batch_id, { etag });
+  if (state.http_status === 304) {
+    retryAfter = state.retry_after ?? retryAfter;
+  } else if (state.http_status === 202) {
+    ({ etag, retry_after: retryAfter } = state);
+  } else {
+    break;
+  }
+}
+
+if (state?.http_status !== 200) throw new Error('Delegated qURL batch did not finish');
+
+if (state.results[0]?.status === 'succeeded') {
+  const qurlId = state.results[0].qurl.qurl_id;
+  const metadata = await client.getDelegatedQurl(qurlId);
+  console.log(metadata.status);
+  await client.deleteDelegatedQurl(qurlId);
+}
+```
+
+The idempotency key must contain 32–256 visible ASCII characters. A UUID meets
+this requirement.
+
+One read makes one HTTP attempt. The caller owns the poll count, total deadline,
+and wait from `retry_after`. A `304` means the prior ETag is still current. A
+`200` contains the terminal, input-ordered results. Keep each returned qURL as
+an opaque bearer link and apply any deployment-specific origin check before
+publishing it.
+
+Delegated DELETE calls are not retried automatically. After a transport failure
+or `503 mutation_outcome_unknown`, retry the same qURL ID until the service
+returns `204`.
+
 ## Opening Portals
 
 Most recipients open qURL links directly and do not use this SDK at all. If
@@ -201,6 +375,7 @@ const { createPortalOpener } = require('@layervai/qurl/node');
 async function uploadPrivateObject(uploadBody) {
   const opener = createPortalOpener({
     qurl: process.env.PRIVATE_UPLOAD_QURL,
+    expectedCRID: process.env.PRIVATE_UPLOAD_CRID ?? '', // Independently held; missing fails closed.
   });
   try {
     await opener.start();
@@ -378,9 +553,9 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `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) |
+| `getConnectorResource(crid)` / `getConnectorResourceBySlug(slug)` | Load a validated Connector resource by immutable identity |
+| `deleteConnectorResource(crid)` | Revoke a Connector resource by CRID |
+| `resourceByCrid(crid)` | Handle from a stored CRID (no API call) |
 | `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |
 
 ### REST-shaped methods
@@ -442,7 +617,7 @@ if (result.failed > 0) {
 
 Non-400 errors (401, 403, 429, 5xx, and unexpected 400 body shapes) still throw the appropriate `QURLError` subclass.
 
-**Slimmer per-item shape** — `BatchItemSuccess` returns `{ resource_id, qurl_link, qurl_site, expires_at? }` per item. Unlike single `client.create()`, the batch response intentionally **omits `qurl_id` and `label`** to keep the payload compact. If you migrate a per-item `create()` loop to `batchCreate` and rely on `qurl_id` for downstream addressing, fetch each via `client.get(resource_id)` after the batch (or stay on the single-create path).
+**Slimmer per-item shape** — `BatchItemSuccess` returns `{ crid, resource_id, qurl_link, qurl_site, expires_at? }` per item. Unlike single `client.create()`, the batch response intentionally **omits `qurl_id` and `label`** to keep the payload compact. If you migrate a per-item `create()` loop to `batchCreate` and rely on `qurl_id` for downstream addressing, check `item.crid` is present, then fetch each via `client.get(item.crid)` after the batch (or stay on the single-create path).
 
 **Result ordering** — `result.results` is **not** guaranteed to be sorted by `index`. Each entry's `index` field carries the position in the original `items` array, so build per-input-position state by keying on `r.index` (e.g., `for (const r of result.results) { byInputIndex[r.index] = r; }`) rather than relying on iteration order.
 
@@ -488,6 +663,7 @@ try {
 | `ServerError` | 5xx | Server-side failure |
 | `NetworkError` | — | Connection failure |
 | `TimeoutError` | — | Request exceeded timeout |
+| `DelegatedBatchOutcomeUnknownError` | — | Dispatched batch create needs reconciliation |
 
 Client-detected failures use `status: 0` with a discriminating `code`:
 `"client_validation"` for bad input caught before a request, and — on the
@@ -504,7 +680,8 @@ const page = await client.list({ limit: 10, status: 'active' });
 
 // Auto-paginate through all results
 for await (const qurl of client.listAll({ status: 'active' })) {
-  console.log(qurl.resource_id);
+  if (!qurl.crid) throw new Error("The API response has no resource CRID");
+  console.log(qurl.crid);
 }
 ```
 
@@ -588,6 +765,10 @@ SDK-generated keys require `globalThis.crypto.getRandomValues`, which is availab
 ## Security Notes
 
 - Treat API keys and qURL links like credentials. Do not log them.
+- Resource/qURL path arguments reject pasted access tokens and full URLs before
+  dispatch without echoing the caller input. Pass the opaque identifier returned
+  by the API (public resource key or CRID); never derive it from a secret qURL
+  link. Private `r_` storage IDs are not public API identifiers.
 - 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
@@ -651,3 +832,139 @@ When upgrading, check the release notes for migration guidance — recent breaki
 ## License
 
 MIT
+
+Resource verification requires Web Crypto (`crypto.subtle`). In browsers, use
+an HTTPS page or localhost. Raw REST response types keep `crid` optional;
+resource handles and portals require a validated CRID.
+
+## Node producer runtime (SDK 2.x, NHP 1.1)
+
+The SDK implements the producer lifecycle in TypeScript. A small optional native
+package, `@layervai/qurl-state-fs`, supplies descriptor-relative filesystem
+operations on Linux and macOS. There is no bundled Go runtime. The portable
+`@layervai/qurl` entry point does not load the native module.
+
+```ts
+import { FileAgentState, connectAgentRuntime } from '@layervai/qurl/node';
+
+const store = new FileAgentState('/private/agent/state.json');
+const runtime = await connectAgentRuntime(store, {
+  hub: { host: 'hub.nhp.layerv.ai', port: 443, server_public_key_b64: hubPublicKey },
+  headless: true,
+  enrollmentCredential: bootstrapCredential,
+});
+try {
+  // runtime.client uses the durable device credential, with bounded reloads.
+  const grant = await runtime.knock(knockResourceID, {
+    protectedResourceID: crid, runID: '0123456789abcdef', runAttempt: 1n,
+  });
+  // Keep the original receipt. It retains the issuing cell across relocation.
+  await runtime.retire(grant.receipt);
+} finally {
+  await runtime.close();
+  store.close();
+}
+```
+
+A registered state opens without enrollment or network work while its assignment
+lease is current. An explicit Hub option or the `hub` field in `QURL_DEPLOYMENT`
+provides refresh trust. `runtime.refresh()` handles assignment renewal and
+relocation. `knock()` attempts renewal near lease expiry and refuses expired
+assignments. Account enrollment uses an explicit `otpProvider` instead of
+`headless`. Resume an interrupted enrollment with the same credential and
+metadata. The SDK persists activation and completion replay authority before
+sending the corresponding mutation.
+
+`recoverAgentRuntime(store, recoveryCredential, { hub })` starts explicit device
+credential recovery. It persists the issue nonce, replacement candidate, and
+recovery horizon. It saves the recovered credential before mandatory assignment
+refresh. A failed refresh resumes without another recovery grant. No startup
+path silently resets an existing identity.
+
+Legacy pre-v6 pending-completion state remains readable, but enrollment returns
+`RECOVERY_MIGRATION_REQUIRED` without UDP or state changes. Those records lack
+an authenticated recovery deadline; explicit recovery or reprovisioning is required.
+Filesystem state creation honors the process umask and creates missing ancestors.
+Keep owner read/write/search permissions enabled (for example, umask `077`);
+unsafe existing permissions or an incompatible umask fail closed.
+
+`FileAgentState` uses a private directory, mode 0600 files, a process-safe setup
+lock, exclusive temporary files, file and directory fsync, and atomic replacement.
+It rejects symlinks, hard links, unsafe permissions, and directory or lock
+replacement. Await `runtime.close()` before closing the store. Inside `withLock`,
+use the supplied locked handle; using the outer store waits until the lock timeout.
+Crash-abandoned `.qurl-*` temporary files remain private but need offline cleanup;
+automatic sweeps could race other state files in the same directory. Filesystem state
+uses synchronous native I/O, including fsync, on the event loop. Use local storage;
+slow or network filesystems can block the process. Continuity checks also run before
+lifecycle datagrams and cannot be cached safely across external directory changes.
+An existing state directory must be owned by the process user with mode 0700.
+On macOS, `/var`, `/tmp`, and `/etc` resolve through their standard `/private` paths.
+A save error after rename can mean the new state is present but its durability is
+unconfirmed; do not assume the previous state remains. Filesystem state
+currently requires Linux or macOS; unsupported platforms fail closed. Install
+scripts may be disabled when a matching prebuilt native binary is available.
+Linux x64/arm64 prebuilds distinguish glibc and musl; CI tests Ubuntu 24.04 and
+Alpine 3.22. macOS prebuilds cover x64 and arm64.
+
+For sealed state, use `openSealedFileAgentState(path, providerID, keyWrapper,
+expectedAgentID)`. Each save uses a fresh AES-256-GCM key and verifies wrapping and
+unwrapping before commit. The envelope is compatible with the pinned Go SDK.
+Sealing authenticates the agent, provider, purpose, version, and wrapped-key
+metadata. It does not detect rollback to an older valid envelope. JavaScript
+strings cannot be reliably erased; avoid logging state or credentials.
+
+AWS adapters are separate exports from `@layervai/qurl-aws` (ESM and CommonJS).
+Install the AWS client for the subpath you use: `/ssm`, `/secrets-manager`, or
+`/kms`. These clients are optional peer dependencies. Importing the root barrel
+requires all three clients.
+
+
+- `createSSMAgentStateStore(ssmClient, parameterName, { kmsKeyID, tier })` stores
+  SecureString parameters and enforces tier size limits.
+- `createSecretsManagerAgentStateStore(secretsClient, secretID, kmsKeyID)` handles
+  missing-secret creation races with one write token.
+- `createKMSAgentStateKeyWrapper(kmsClient, keyID)` wraps only the data key and
+  authenticates all four state-binding fields in the KMS encryption context.
+
+SSM and Secrets Manager stores serialize lifecycle calls within one store handle.
+Loads outside a lifecycle lock can read the previous committed state.
+They require one process to own each state object: these services do not provide
+an agent setup transaction lock. KMS is a key wrapper, not a state store.
+
+## Explicit relay and discovery
+
+Native UDP remains the default transport. An unknown native cell fails closed, including
+when a relay allowlist exists. Select `transport: 'relay'` explicitly to use HTTPS
+relay. Explicit relay trust uses signed qv2 claims and the relay allowlist, not
+the native cell catalog. Relay URLs must match that deployment trust.
+Redirects and oversized responses are refused. A hostname-only allowlist entry
+authorizes all ports on that host; use `host:port` to limit the port.
+
+`createStaticProvider(deployment)` snapshots fixed trust. For discovery, use
+`createDiscoveryProvider({ fetcher, pinSHA256, manifestKeys, requireSignature,
+minVersion, expectedProfile })` and `createHTTPManifestFetcher(httpsURL)`. Supply
+a manifest pin or signing keys. Discovery is relay-only and requires
+`transport: 'relay'`; native UDP requires a static cell catalog. Discovery verifies the domain-separated low-S
+signature when configured, validity times, profile, and monotonic version floor.
+It never returns stale trust after a failed refresh. Persist `minVersion` in
+configuration when downgrade protection must survive process restarts.
+Like Go, discovery fetches on each resolution, including renewal retries; it has
+no built-in cache. Use static trust for high-volume opens, or supply a provider
+with a deployment-owned refresh policy that refuses expired or failed-refresh trust.
+
+```ts
+const opener = createPortalOpener({ qurl: signedLink, provider, transport: 'relay' });
+```
+
+The SHA-pinned reviewed baseline and behavior gates are in `parity-manifest.json`.
+CI reports the candidate SHA and tests that candidate against pinned Go behavior.
+It does not require release or dependency PRs to match the baseline tree.
+Run `npm run build`, `npm test`, `npm run smoke:dist`, and `npm run parity:go`.
+Set `QURL_GO_REFERENCE` to a clean checkout at the manifest's exact Go revision.
+The direct gate compares producer wire bytes and sealed-state reads and writes
+across both languages. It also runs the TypeScript lifecycle against a local Go UDP
+peer: registration, restart, relocation, exact retirement, and credential recovery.
+This checks protocol interoperability; the peer is not a sandbox authority.
+Shared conformance vectors cover assignment, registration,
+OTP, and completion packet construction and reply decryption.

package/dist/cjs/client.d.ts

@@ -1,4 +1,7 @@
-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";
+import { ShareLink } from "./share.js";
+import type { AccessCodeListOutput, ApiKey, ApiKeyListOutput, ApiKeyRequestScope, BillingInvoiceListOutput, BatchCreateInput, BatchCreateOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationListOutput, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateDelegatedQurlBatchInput, CreateDelegatedQurlBatchOptions, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, Domain, DomainListOutput, DomainVerifyResult, DelegatedQurl, DelegatedQurlBatchAccepted, GetDelegatedQurlBatchOptions, GetDelegatedQurlBatchOutput, 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, ShareResourceOptions, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCurrentPeriod, UsageDaily, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventTypeInfo, WebhookListOutput, WebhookWithSecret } from "./types.js";
+/** Narrow a response scope before reusing it in a create/update request. */
+export declare function isApiKeyRequestScope(scope: string): scope is ApiKeyRequestScope;
 /**
  * Shape of qurl-go's offline signed-fragment links: three or more
  * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
@@ -77,34 +80,34 @@ export declare class QURLClient {
      */
     protectUrl(targetUrl: string, opts?: ProtectUrlOptions, requestOptions?: RequestOptions): Promise<ProtectedResource>;
     /**
-     * Return a portal-minting handle for a stored resource id, without an API
+     * Return a portal-minting handle for a stored CRID, without an API
      * call.
      *
-     * Use when you persisted a LayerV resource id and want to mint more
-     * portals for it (qurl-go: `Client.ResourceByID`):
+     * Use when you persisted a LayerV CRID and want to mint more
+     * portals for it (qurl-go: `Client.ResourceByCRID`):
      *
      * ```ts
-     * const resource = client.resourceById("r_demo1234567");
+     * const resource = client.resourceByCrid(storedCrid);
      * const portal = await resource.createPortal({ validFor: "1h" });
      * ```
      *
      * The handle carries no server metadata; use {@link getResource} when you
      * need the full resource details.
      */
-    resourceById(id: string): ProtectedResource;
+    resourceByCrid(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 a qURL Connector resource by its CRID. */
+    getConnectorResource(crid: string): Promise<ConnectorResource>;
     /** Fetch the single active qURL Connector resource for an immutable slug. */
     getConnectorResourceBySlug(slug: string): Promise<ConnectorResource>;
     /**
-     * Revoke a qURL Connector resource by immutable public resource ID.
+     * Revoke a qURL Connector resource by CRID.
      *
      * The API does not apply Idempotency-Key replay to DELETE. After an
      * outcome-unknown failure, reconcile by ID before issuing a deliberate retry.
      */
-    deleteConnectorResource(resourceId: string): Promise<void>;
+    deleteConnectorResource(crid: string): Promise<void>;
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
      *
@@ -112,7 +115,7 @@ 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
-     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
+     * CRID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
@@ -128,7 +131,7 @@ export declare class QURLClient {
      *
      * Convenience for one-off scripts (qurl-go: `Client.CreatePortalForURL`).
      * The returned resource handle is reusable for minting more portals but
-     * carries only the resource id and the caller-supplied target URL; use
+     * carries the CRID, verification key, and the caller-supplied target URL; use
      * {@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
@@ -223,11 +226,30 @@ export declare class QURLClient {
      * ```
      */
     batchCreate(input: BatchCreateInput, options?: RequestOptions): Promise<BatchCreateOutput>;
+    /**
+     * Start one durable delegated qURL batch. The SDK sends this mutation once.
+     * If the result may have committed, retry explicitly with the same key and
+     * semantic body.
+     */
+    createDelegatedQurlBatch(input: CreateDelegatedQurlBatchInput, options: CreateDelegatedQurlBatchOptions): Promise<DelegatedQurlBatchAccepted>;
+    /**
+     * Read one delegated qURL batch state. One call performs one logical read;
+     * callers retain control of the poll count and total deadline.
+     */
+    getDelegatedQurlBatch(batchId: string, options?: GetDelegatedQurlBatchOptions): Promise<GetDelegatedQurlBatchOutput>;
+    /** Read owner-visible metadata for one delegated qURL. */
+    getDelegatedQurl(qurlId: string): Promise<DelegatedQurl>;
+    /**
+     * Revoke one delegated qURL. DELETE is never retried automatically. A 503
+     * `mutation_outcome_unknown` is safe to retry with the same qURL ID.
+     */
+    deleteDelegatedQurl(qurlId: string): Promise<void>;
     /**
      * Get a qURL resource and its access tokens.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix); the API resolves `q_` IDs to the parent resource automatically.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      */
     get(id: string): Promise<QURL>;
     /**
@@ -258,17 +280,17 @@ export declare class QURLClient {
     /**
      * Delete (revoke) a qURL resource and all its access tokens.
      *
-     * Only accepts a resource ID (`r_` prefix), not a qURL display ID (`q_`
-     * prefix). Per the OpenAPI spec: *"Requires a resource ID (r_ prefix).
-     * To revoke a single token, use DELETE /v1/resources/:id/qurls/:qurl_id"*.
-     * A client-side prefix check catches the mistake before the API round-trip.
+     * Requires a CRID returned by the API. To revoke one qURL, use
+     * {@link revokeResourceQurl} instead.
+     *
+     * @throws {ValidationError} If `id` is not a canonical CRID.
      */
     delete(id: string): Promise<void>;
     /**
      * Extend a qURL's expiration.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix). Convenience method — delegates to {@link update} with only the
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix). Delegates to {@link update} with only the
      * expiration fields. `ExtendInput` shares its `extend_by` / `expires_at`
      * fields with `UpdateInput` but is *narrower in two ways*: (1) exactly
      * one of the two must be present (XOR via `?: never`), where `UpdateInput`
@@ -283,8 +305,9 @@ export declare class QURLClient {
     /**
      * Update a qURL — extend expiration, change description, rename tags.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix); the API resolves `q_` IDs to the parent resource automatically.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      */
     update(id: string, input: UpdateInput, options?: RequestOptions): Promise<QURL>;
     /**
@@ -292,8 +315,9 @@ export declare class QURLClient {
      *
      * Portal-flow equivalent: {@link createPortal}.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix); the API resolves `q_` IDs to the parent resource automatically.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      *
      * Passing `{}` or an object with all fields `null`/`undefined` is
      * equivalent to omitting the second argument: no body is sent, and the
@@ -342,6 +366,13 @@ export declare class QURLClient {
      * Portal-flow equivalent: {@link createPortal} (same endpoint).
      */
     createQurlForResource(id: string, input?: CreateQurlForResourceInput, options?: RequestOptions): Promise<CreateOutput>;
+    /**
+     * Mint a fresh, short-lived share link for an existing CRID.
+     * The returned link is secret and is not retrievable after this response.
+     * If you hold the trusted resource DER SPKI, call `ShareLink.verifyCrid()`
+     * before delivery to verify that the response CRID derives from that key.
+     */
+    shareResource(id: string, options?: ShareResourceOptions, requestOptions?: RequestOptions): Promise<ShareLink>;
     /** Revoke a specific qURL token on a resource. */
     revokeResourceQurl(id: string, qurlId: string): Promise<void>;
     /** Update a specific qURL token on a resource. */
@@ -505,19 +536,19 @@ export declare class QURLClient {
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceById} —
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceByCrid} —
  * 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 public resource ID. */
-    readonly id: string;
+    /** The public resource CRID. */
+    readonly crid: string;
     /** The private URL protected by this resource, when known. */
     readonly targetUrl?: string;
     /**
      * Full server-populated {@link Resource} metadata when the handle came
-     * from an API response; `undefined` for {@link QURLClient.resourceById}
+     * from an API response; `undefined` for {@link QURLClient.resourceByCrid}
      * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
      */
     readonly details?: Resource;
@@ -550,9 +581,9 @@ declare const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN: unique symbol;
  */
 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 resourcePublicKey: string;
+    /** Required public identifier, verified against the returned resource key. */
+    readonly crid: string;
     readonly connectorRoutingId: string;
     readonly knockResourceId: string;
     readonly slug: string;