@layervai/qurl 0.5.0 → 0.7.0

package/README.md

@@ -68,11 +68,15 @@ 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 { 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',
@@ -84,12 +88,52 @@ 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.
 
-If you persist the resource id, future calls do not need to recreate the
+`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(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.
+
+`ensureConnectorResource` and `deleteConnectorResource` throw
+`ConnectorResourceOutcomeUnknownError` when a dispatched mutation may have
+committed but its response cannot prove the result. Reconcile by immutable slug
+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.
+
+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 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 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
@@ -116,11 +160,105 @@ const portal = await resource.createPortal({
 });
 ```
 
+`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 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. See the native opener example above.
+`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`.
+
 ## Opening Portals
 
 Most recipients open qURL links directly and do not use this SDK at all. If
@@ -336,8 +474,10 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `protectUrl(targetUrl, opts?)` | Protect a private URL → portal-minting `ProtectedResource` handle |
 | `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` |
-| `connectorResource(connectorId)` | Handle for a service qURL Connector already protects |
-| `resourceById(id)` | Handle from a stored resource id (no API call) |
+| `ensureConnectorResource(slug, requestOptions?)` | Find or create an active Connector resource by immutable slug |
+| `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
@@ -399,7 +539,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.
 
@@ -449,7 +589,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).
 
@@ -461,7 +601,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);
 }
 ```
 
@@ -545,6 +686,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
@@ -608,3 +753,7 @@ 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.

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, 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, 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,38 +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 CRID. */
+    getConnectorResource(crid: 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 CRID.
      *
-     * 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(crid: string): Promise<void>;
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
      *
@@ -116,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
-     * resource id (`r_` prefix). 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
@@ -132,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
@@ -230,8 +229,9 @@ export declare class QURLClient {
     /**
      * 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>;
     /**
@@ -262,17 +262,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`
@@ -287,8 +287,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>;
     /**
@@ -296,8 +297,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
@@ -346,6 +348,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. */
@@ -509,20 +518,19 @@ 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.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 resource id (`r_` prefix). */
-    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;
@@ -540,3 +548,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 resourcePublicKey: string;
+    /** Required public identifier, verified against the returned resource key. */
+    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 {};