@layervai/qurl 0.6.0 → 0.7.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,97 @@ 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
@@ -378,9 +475,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 +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.
 
@@ -504,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);
 }
 ```
 
@@ -588,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
@@ -651,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,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
@@ -226,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>;
     /**
@@ -258,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`
@@ -283,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>;
     /**
@@ -292,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
@@ -342,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. */
@@ -505,19 +518,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 +563,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;