@byok-sdk/cloud 0.4.2 → 0.6.0

package/README.md

@@ -6,6 +6,25 @@ logic but no durable database or object-storage driver.
 
 Pair it with `@byok-sdk/cloud-dataplane` for Postgres + R2 production storage.
 
+`authenticateHostedDeviceAssertion()` is the hosted connector-binding auth
+composition. It adapts the current `DeviceDirectory` row and `CloudCrypto` to
+core's single-use authenticator; callers must inject a replay authority and
+trusted deployment bindings. Create durable connector state only after it
+returns a principal. OAuth refresh tokens and the resulting long-lived profile
+remain host-owned and are never stored by this API.
+
+```ts
+const authenticated = await authenticateHostedDeviceAssertion(assertion, {
+  devices,
+  crypto,
+  replay,
+  clock,
+  expected: { issuer, productId, audience: 'connector-binding' },
+});
+if (authenticated === undefined) throw new Error('unauthorized');
+await connectorProfiles.bind(authenticated.device, providerLogin);
+```
+
 Hosted compositions enqueue the distinct toolset offer message explicitly:
 
 ```ts

package/dist/auth/device-assertion.d.ts

@@ -0,0 +1,18 @@
+import { type AuthenticatedDeviceAssertion, type Clock, type DeviceAssertionExpectedBinding, type DeviceAssertionReplayAuthority } from '@byok-sdk/core';
+import type { CloudCrypto } from '../crypto/port';
+import type { DeviceDirectory } from '../stores/ports';
+export interface HostedDeviceAssertionAuthDeps {
+    readonly devices: DeviceDirectory;
+    readonly crypto: CloudCrypto;
+    readonly replay: DeviceAssertionReplayAuthority;
+    readonly clock: Clock;
+    readonly expected: DeviceAssertionExpectedBinding;
+    readonly maxLifetimeMs?: number;
+}
+/**
+ * Hosted composition for an assertion exchange endpoint. The returned
+ * principal is current device-directory authority; the assertion is consumed
+ * before success is returned. Connector sessions minted afterward remain
+ * host-owned and are never represented by this short-lived credential.
+ */
+export declare function authenticateHostedDeviceAssertion(input: unknown, deps: HostedDeviceAssertionAuthDeps): Promise<AuthenticatedDeviceAssertion | undefined>;

package/dist/cloud.d.ts

@@ -14,7 +14,7 @@
  * quietly undo that — a Running/session map — is asserted absent by
  * `src/__tests__/constraints.test.ts`.
  */
-import { type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId } from '@byok-sdk/core';
+import { type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId, type TenantReadiness } from '@byok-sdk/core';
 import type { ActivityTail } from './activity';
 import type { ApprovalTimelineTail } from './approval-timeline';
 import { type Envelope, type TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
@@ -127,17 +127,18 @@ export interface ByokCloud {
     enqueueOffer(tenant: TenantId, deviceId: string, input: EnqueueOfferInput): Promise<EnqueuedOffer>;
     /** Host control plane: enqueue the additive fail-closed offer variant that requires local MCP toolsets. */
     enqueueToolsetOffer(tenant: TenantId, deviceId: string, input: EnqueueToolsetOfferInput): Promise<EnqueuedOffer>;
+    /** Host control plane: durably request cancellation by tenant/task id. Idempotent. */
+    cancelTask(tenant: TenantId, taskId: string, reason?: string): Promise<TaskAttempt>;
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     /** The recorded terminal for a task — the first one, re-encoded canonically under the frozen v1 codec (see `recordTerminal`, `inbound.ts`: the stored body is `encodeEnvelope` of the zod-parsed envelope, not the device's original byte sequence). */
     readTerminalReceipt(tenant: TenantId, taskId: string): Promise<RequestReceipt | undefined>;
     /**
      * Host control plane: the same first terminal, decoded into the typed read
      * model ({@link TerminalResult}) so a host reads result fields, not envelope
-     * prose. `undefined` ONLY means no terminal fact is recorded yet:
-     * first-terminal-wins is inherited from the receipt store
-     * ({@link ByokCloud.readTerminalReceipt} reads the same row), and a declined
-     * task records no terminal at all — use {@link ByokCloud.readTaskAttempt}
-     * for that attempt status. An absent `document` covers both a legacy
+     * prose. An accepted host cancellation tombstone outranks a later device
+     * receipt; the raw receipt remains readable as device evidence through
+     * {@link ByokCloud.readTerminalReceipt}. `undefined` means neither fact
+     * exists. An absent `document` covers both a legacy
      * pre-`result-document` daemon build and a daemon with no `resultDocument`
      * extractor; a receipt whose body is not a terminal envelope throws rather
      * than returning a best-effort shape.
@@ -151,6 +152,8 @@ export interface ByokCloud {
     /** Human review authority. Device routes cannot produce `done`. */
     acceptBoardItem(tenant: TenantId, itemId: string): Promise<BoardItem>;
     listPresence(tenant: TenantId): Promise<readonly PresenceHint[]>;
+    /** SDK-owned observation only; never a scheduler or execution authority. */
+    readTenantReadiness(tenant: TenantId): Promise<TenantReadiness>;
     readActivity(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
     readApprovalTimeline(tenant: TenantId, taskId: string): Promise<ApprovalTimelineTail | undefined>;
 }

package/dist/errors.d.ts

@@ -41,6 +41,8 @@ export declare const CLOUD_ERROR_CODES: {
     readonly terminal_receipt_unreadable: 'terminal_receipt_unreadable';
     /** A progress/activity batch exceeded the configured event or byte ceiling. */
     readonly activity_batch_too_large: 'activity_batch_too_large';
+    /** Host control-plane task lookup is tenant-closed and found no task. */
+    readonly task_not_found: 'task_not_found';
 };
 export type CloudErrorCode = (typeof CLOUD_ERROR_CODES)[keyof typeof CLOUD_ERROR_CODES];
 export declare class ByokCloudError extends Error {

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export { authenticateBearer, extractBearerToken } from './auth/bearer';
 export type { BearerAuthDeps } from './auth/bearer';
 export { DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, authenticateDeviceProof, } from './auth/device-proof';
 export type { AuthenticatedDeviceProof, DeviceProofAuthDeps, DeviceProofRequestBinding, } from './auth/device-proof';
+export { authenticateHostedDeviceAssertion } from './auth/device-assertion';
+export type { HostedDeviceAssertionAuthDeps } from './auth/device-assertion';
 export { DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, PAIRING_CODE_TTL_MS, createAuthPlane, } from './auth/plane';
 export type { AuthPlane, AuthPlaneDeps, MintedAccessToken, PairInput } from './auth/plane';
 export { createWebCrypto } from './crypto/web-crypto';
@@ -59,6 +61,6 @@ export { TruthCommitError, isTruthCommitError } from './truth/errors';
 export type { TruthCommitErrorCode } from './truth/errors';
 export { CLOUD_STORE_NAMES, TASK_ATTEMPT_STATUSES } from './stores/ports';
 export { CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS } from './stores/ports-contract';
-export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, } from './stores/ports';
-export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryActivityStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
+export type { BlobContent, BlobContentProxy, BlobDeclaration, BlobObservation, BlobWriteResult, CloudBlobStore, CloudStoreName, CloudStores, DeviceDirectory, DeviceRecord, DeviceRegistration, InboundDedupStore, InboundRateLimiter, NonceStore, PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore, ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore, RequestReceipt, RequestReceiptStore, TaskAttempt, TaskAttemptStatus, TaskAttemptStore, TaskCancellationMutation, TaskCancellationRequest, TaskCancellationStore, } from './stores/ports';
+export { AllowAllRateLimiter, BLOB_URL_TTL_MS, DEDUP_RING_CAPACITY, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryActivityStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryRequestReceiptStore, InMemoryProofRequestReceiptStore, InMemoryTaskAttemptStore, InMemoryTaskCancellationStore, NONCE_TTL_MS, createInMemoryBlobs, createInMemoryCloudStores, } from './stores/in-memory/index';
 export type { InMemoryBlobStoreOptions, InMemoryBlobs, InMemoryCloudComposition, } from './stores/in-memory/index';