@oatscenter/trellis 0.100.0-rc.1

package/device.js

@@ -0,0 +1,687 @@
+export { checkDeviceActivation } from "./device/activation.js";
+import { AsyncResult, Result, UnexpectedError, } from "@oatscenter/result";
+import { ulid } from "ulid";
+import { decodeTrellisHttpError, TrellisHttpError } from "./auth/http_error.js";
+import { connectClientWithDeps, } from "./client_connect.js";
+import { ContractResourceBindingsSchema, } from "./participant.js";
+import { deriveDeviceConfirmationCode, deriveDeviceIdentity, deriveDeviceUserCompanion, requestDeviceEnrollment, verifyDeviceConfirmationCode, waitForDeviceActivation, } from "./auth/device_activation.js";
+import { sessionProofRequestDigest } from "./auth/session_proof.js";
+import { base64urlDecode, base64urlEncode, canonicalizeJsonValue, sha256, utf8, } from "./auth/utils.js";
+import { estimateMidpointClockOffsetMs } from "./auth/time.js";
+import { createAuth } from "./auth/session_auth.js";
+import { AuthorizationContextRefreshResponseSchema } from "./auth/authorization/types.js";
+import { DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS, loadDefaultRuntimeTransport, selectRuntimeTransportServers, } from "./runtime_transport.js";
+import { ServiceHealthRuntime, } from "./service/runtime/health.js";
+import { publishHealthHeartbeatSample } from "./health_transport.js";
+import { Trellis } from "./session.js";
+import { logger as noopLogger } from "./globals.js";
+import { TransportError } from "./errors/index.js";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { installConnectionAvailability, observeNatsTrellisConnection, } from "./connection.js";
+import { AuthorizationContextCache, AuthorizationContextRefreshError, AuthorizationProviderCache, startAuthorizationContextRefresh, } from "./auth/authorization_context.js";
+import { createCallerRuntime } from "./caller.js";
+import { bindApiRoutes, getParticipantRuntime, participantAvailability, participantEvidence, refreshApiRoutes, } from "./participant_runtime/participant.js";
+function deviceConnectResult(promise) {
+    return AsyncResult.from(promise.then((value) => Result.ok(value), (cause) => Result.err(cause instanceof TransportError
+        ? cause
+        : new UnexpectedError({ cause }))));
+}
+const DeviceBootstrapInstallationSchema = Type.Object({
+    ...AuthorizationContextRefreshResponseSchema.properties,
+    authorization: Type.Object({
+        participantId: Type.String({ minLength: 1 }),
+        participantDigest: Type.String({ minLength: 1 }),
+        resourceRuntime: ContractResourceBindingsSchema,
+    }),
+});
+const DeviceBootstrapReadySchema = Type.Object({
+    ...DeviceBootstrapInstallationSchema.properties,
+    companion: Type.Optional(Type.Object({
+        participantId: Type.String({ minLength: 1 }),
+        loginSessionId: Type.String({ minLength: 1 }),
+        required: Type.Boolean(),
+        installation: DeviceBootstrapInstallationSchema,
+    })),
+});
+function normalizeRootSecret(rootSecret) {
+    if (typeof rootSecret === "string") {
+        const decoded = base64urlDecode(rootSecret.trim());
+        if (decoded.length === 0)
+            throw new Error("rootSecret must not be empty");
+        return decoded;
+    }
+    if (rootSecret.length === 0)
+        throw new Error("rootSecret must not be empty");
+    return rootSecret;
+}
+const defaultDeps = {
+    loadTransport: loadDefaultRuntimeTransport,
+    now: () => Date.now(),
+};
+function transportCauseContext(cause) {
+    if (cause instanceof Error) {
+        return { causeName: cause.name, causeMessage: cause.message };
+    }
+    return { cause: String(cause) };
+}
+function createTransportError(args) {
+    return new TransportError({
+        code: args.code,
+        message: args.message,
+        hint: args.hint,
+        cause: args.cause,
+        context: {
+            ...(args.context ?? {}),
+            ...(args.cause === undefined ? {} : transportCauseContext(args.cause)),
+        },
+    });
+}
+async function readJsonResponse(response, args) {
+    try {
+        return await response.json();
+    }
+    catch (cause) {
+        throw createTransportError({
+            ...args,
+            cause,
+        });
+    }
+}
+function resolveDeviceLogger(log) {
+    if (log === false) {
+        return noopLogger;
+    }
+    return log ?? noopLogger;
+}
+function createInvalidConfirmationCodeTransportError(context) {
+    return createTransportError({
+        code: "trellis.device.invalid_confirmation_code",
+        message: "The device confirmation code is invalid.",
+        hint: "Retry with the current confirmation code for this activation, or restart activation if the code is no longer valid.",
+        context,
+    });
+}
+function createActivatedLocalState(localState) {
+    return {
+        ...localState,
+        status: "activated",
+    };
+}
+function assertActivationStateMatchesIdentity(args) {
+    if (args.localState.publicIdentityKey !== args.publicIdentityKey) {
+        throw createTransportError({
+            code: "trellis.device.activation_state_mismatch",
+            message: "Local device activation state does not match the provided root secret.",
+            hint: "Use the activation state for the same device identity, or start a new activation for this root secret.",
+            context: {
+                statePublicIdentityKey: args.localState.publicIdentityKey,
+                publicIdentityKey: args.publicIdentityKey,
+            },
+        });
+    }
+}
+function assertActivationStateMatchesContract(args) {
+    if (args.localState.participantId !== args.participantId) {
+        throw createTransportError({
+            code: "trellis.device.activation_state_contract_mismatch",
+            message: "Local device activation state does not match the requested device participant.",
+            hint: "Use activation state for the same device contract, or start activation again for this contract digest.",
+            context: {
+                stateParticipantId: args.localState.participantId,
+                participantId: args.participantId,
+            },
+        });
+    }
+}
+function createActivationSession(args) {
+    assertActivationStateMatchesIdentity({
+        localState: args.localState,
+        publicIdentityKey: args.identity.publicIdentityKey,
+    });
+    assertActivationStateMatchesContract({
+        localState: args.localState,
+        participantId: args.participantId,
+    });
+    const activatedState = createActivatedLocalState(args.localState);
+    return {
+        activationUrl: args.localState.activationUrl,
+        localState: args.localState,
+        waitForOnlineApproval: async (opts) => {
+            if (args.localState.status === "activated") {
+                return activatedState;
+            }
+            await waitForDeviceActivation({
+                trellisUrl: args.trellisUrl,
+                publicIdentityKey: args.identity.publicIdentityKey,
+                identitySeed: args.identity.identitySeed,
+                activationKey: args.identity.activationKey,
+                participantId: args.provisioned.participantId,
+                ...participantEvidence(args.participant),
+                provisioningSecret: args.provisioned.provisioningSecret ?? undefined,
+                nonce: args.localState.nonce,
+                signal: opts?.signal,
+                sessionIdentity: args.sessionIdentity,
+                connectionId: args.connectionId,
+                companion: args.companion,
+            });
+            return activatedState;
+        },
+        acceptConfirmationCode: async (code) => {
+            if (args.localState.status === "activated") {
+                return activatedState;
+            }
+            const ok = await verifyDeviceConfirmationCode({
+                activationKey: args.identity.activationKey,
+                publicIdentityKey: args.identity.publicIdentityKey,
+                nonce: args.localState.nonce,
+                confirmationCode: code,
+            });
+            if (!ok) {
+                throw createInvalidConfirmationCodeTransportError({
+                    publicIdentityKey: args.identity.publicIdentityKey,
+                    instanceId: args.localState.instanceId,
+                    deploymentId: args.localState.deploymentId,
+                });
+            }
+            return activatedState;
+        },
+    };
+}
+async function fetchDeviceBootstrap(args) {
+    const sessionAuth = args.sessionAuth ?? await createAuth({
+        sessionKeySeed: base64urlEncode(crypto.getRandomValues(new Uint8Array(32))),
+    });
+    const requestStartedAtMs = args.now();
+    const issuedAt = Math.trunc(requestStartedAtMs + args.offsetState.serverClockOffsetMs);
+    const requestId = ulid();
+    const identityAuth = await createAuth({
+        sessionKeySeed: base64urlEncode(args.deviceIdentity.identitySeed),
+    });
+    const deviceIdentityKeyId = base64urlEncode(await sha256(base64urlDecode(identityAuth.sessionKey)));
+    const unsigned = {
+        identityKeyId: deviceIdentityKeyId,
+        sessionKey: sessionAuth.sessionKey,
+        connectionId: args.connectionId ?? ulid(),
+        requestId,
+        iat: issuedAt,
+        name: args.participant.identity,
+        ...participantEvidence(args.participant),
+    };
+    const descriptor = args.participant.companion;
+    let companionInstallationSeedBase64url;
+    let companionSessionSeedBase64url;
+    if (descriptor) {
+        const installation = await deriveDeviceUserCompanion(args.rootSecret, args.trellisUrl, descriptor.participant.identity);
+        companionInstallationSeedBase64url = installation.installationSeedBase64url;
+        const companionAuth = await createAuth({
+            sessionKeySeed: installation.installationSeedBase64url,
+        });
+        companionSessionSeedBase64url = base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
+        const companionSessionAuth = await createAuth({
+            sessionKeySeed: companionSessionSeedBase64url,
+        });
+        const companionRequest = {
+            connectionId: ulid(),
+            requestId: ulid(),
+            issuedAt,
+            sessionKey: companionSessionAuth.sessionKey,
+        };
+        const digest = base64urlEncode(await sha256(utf8(canonicalizeJsonValue({
+            format: "trellis.device.user-companion.v1",
+            origin: new URL(args.trellisUrl).origin,
+            identityKeyId: deviceIdentityKeyId,
+            participantId: descriptor.participant.identity,
+            ...companionRequest,
+        }))));
+        unsigned.companion = {
+            ...companionRequest,
+            proof: base64urlEncode(await companionAuth.sign(base64urlDecode(digest))),
+        };
+    }
+    const response = await fetch(new URL("/bootstrap/device", args.trellisUrl), {
+        method: "POST",
+        signal: args.signal,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            ...unsigned,
+            proof: await identityAuth.signSessionProof({
+                purpose: "deviceBootstrap",
+                origin: new URL(args.trellisUrl).origin,
+                unsignedRequest: unsigned,
+            }),
+        }),
+    });
+    const responseReceivedAtMs = args.now();
+    if (!response.ok)
+        throw await decodeTrellisHttpError(response);
+    const payload = await readJsonResponse(response, {
+        code: "trellis.bootstrap.invalid_response",
+        message: "Trellis returned an invalid device bootstrap response.",
+        hint: "Retry the connection or complete device activation.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+    const ready = Value.Parse(DeviceBootstrapReadySchema, payload);
+    args.offsetState.serverClockOffsetMs = estimateMidpointClockOffsetMs({
+        requestStartedAtMs,
+        responseReceivedAtMs,
+        serverNowSeconds: ready.serverNow / 1_000,
+    });
+    sessionAuth.setServerClockOffsetMs(args.offsetState.serverClockOffsetMs + args.now() - Date.now());
+    return {
+        status: "ready",
+        sessionAuth,
+        connectInfo: {
+            connectionId: ready.runtime.connectionId,
+            participantId: ready.runtime.participantId,
+            participantDigest: ready.authorization.participantDigest,
+            transports: ready.transports,
+            transport: {
+                jwt: ready.routing.bootstrapJwt,
+                jwtExpiresAt: ready.routing.bootstrapJwtExpiresAt,
+                inboxPrefix: ready.runtime.inboxPrefix,
+            },
+            authorizationContext: ready.authorizationContext,
+            apiBindings: ready.apiBindings,
+            resourceBindings: ready.authorization.resourceRuntime,
+        },
+        ...(ready.companion && companionInstallationSeedBase64url &&
+            companionSessionSeedBase64url
+            ? {
+                companion: {
+                    ...ready.companion,
+                    installationSeedBase64url: companionInstallationSeedBase64url,
+                    sessionSeedBase64url: companionSessionSeedBase64url,
+                    bootstrap: ready.companion.installation,
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * @internal Exported for focused tests and platform-specific wrappers.
+ */
+export async function startDeviceActivationWithDeps(args, deps) {
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await deriveDeviceIdentity(rootSecret);
+    const nonce = base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
+    const sessionIdentity = await createAuth({
+        sessionKeySeed: base64urlEncode(crypto.getRandomValues(new Uint8Array(32))),
+    });
+    const connectionId = ulid();
+    const companion = args.participant.companion;
+    if (companion && companion.participant.kind !== "app" &&
+        companion.participant.kind !== "agent") {
+        throw new Error("device companion must be an app or agent");
+    }
+    const companionIdentity = companion
+        ? {
+            participantId: companion.participant.identity,
+            kind: companion.participant.kind,
+            installation: await deriveDeviceUserCompanion(rootSecret, args.trellisUrl, companion.participant.identity),
+        }
+        : undefined;
+    const activation = await requestDeviceEnrollment({
+        trellisUrl: args.trellisUrl,
+        publicIdentityKey: identity.publicIdentityKey,
+        identitySeed: identity.identitySeed,
+        sessionIdentity,
+        connectionId,
+        participantId: args.participant.identity,
+        ...participantEvidence(args.participant),
+        provisioningSecret: args.provisioningSecret,
+        challengeDigest: base64urlEncode(await sha256(utf8(nonce))),
+        confirmationCode: await deriveDeviceConfirmationCode({
+            activationKey: identity.activationKey,
+            publicIdentityKey: identity.publicIdentityKey,
+            nonce,
+        }),
+        companion: companionIdentity,
+    });
+    const activationState = activation.activation;
+    if (activation.state !== "pending" ||
+        typeof activationState?.reviewId !== "string" ||
+        typeof activationState.activationUrl !== "string" ||
+        typeof activationState.principalId !== "string" ||
+        typeof activationState.deploymentId !== "string" ||
+        typeof activationState.instanceId !== "string") {
+        throw createTransportError({
+            code: "device_activation_unavailable",
+            message: "The device does not require activation.",
+            hint: "Connect the device directly.",
+            context: { status: activation.state },
+        });
+    }
+    return await createActivationSession({
+        trellisUrl: args.trellisUrl,
+        participantId: args.participant.identity,
+        identity,
+        provisioned: {
+            participantId: args.participant.identity,
+            provisioningSecret: args.provisioningSecret,
+        },
+        participant: args.participant,
+        now: deps.now,
+        localState: {
+            status: "pending",
+            participantId: args.participant.identity,
+            publicIdentityKey: identity.publicIdentityKey,
+            instanceId: activationState.instanceId,
+            deploymentId: activationState.deploymentId,
+            flowId: activationState.reviewId,
+            nonce,
+            activationUrl: activationState.activationUrl,
+        },
+        sessionIdentity,
+        connectionId,
+        companion: companionIdentity,
+    });
+}
+/**
+ * @internal Exported for focused tests and platform-specific wrappers.
+ */
+export async function resumeDeviceActivationWithDeps(args, deps) {
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await deriveDeviceIdentity(rootSecret);
+    const companion = args.participant.companion;
+    return await createActivationSession({
+        trellisUrl: args.trellisUrl,
+        participantId: args.participant.identity,
+        identity,
+        provisioned: { participantId: args.participant.identity },
+        participant: args.participant,
+        now: deps.now,
+        localState: args.localState,
+        companion: companion
+            ? {
+                participantId: companion.participant.identity,
+                kind: companion.participant.kind,
+                installation: await deriveDeviceUserCompanion(rootSecret, args.trellisUrl, companion.participant.identity),
+            }
+            : undefined,
+    });
+}
+/**
+ * @internal Exported for focused tests; applications should use
+ * `TrellisDevice.connect`.
+ */
+export async function connectDeviceWithDeps(args, deps) {
+    const log = resolveDeviceLogger(args.log);
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await deriveDeviceIdentity(rootSecret);
+    const offsetState = { serverClockOffsetMs: 0 };
+    let bootstrap;
+    while (true) {
+        try {
+            bootstrap = await fetchDeviceBootstrap({
+                trellisUrl: args.trellisUrl,
+                deviceIdentity: identity,
+                rootSecret,
+                participant: args.participant,
+                now: deps.now,
+                offsetState,
+            });
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof TrellisHttpError) || error.status !== 503 ||
+                error.code !== "resource_pending") {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    const connectInfo = bootstrap.connectInfo;
+    const transport = await deps.loadTransport();
+    const authorizationContexts = new AuthorizationContextCache(args.trellisUrl, (input, init) => globalThis.fetch(input, init), deps.now);
+    authorizationContexts.setServerClockOffsetMs(offsetState.serverClockOffsetMs);
+    await authorizationContexts.install(connectInfo.authorizationContext, {
+        bootstrapJwt: connectInfo.transport.jwt,
+        bootstrapJwtExpiresAt: connectInfo.transport.jwtExpiresAt,
+    });
+    const verifiedContext = authorizationContexts.current();
+    if (verifiedContext.context.participantId !== args.participant.identity) {
+        throw new Error("device authorization context belongs to another participant");
+    }
+    const deploymentId = verifiedContext.context.deploymentId;
+    const instanceId = verifiedContext.context.instanceId;
+    if (!deploymentId || !instanceId) {
+        throw new Error("device authorization context is missing its deployment assignment");
+    }
+    const sessionOptions = await bootstrap.sessionAuth.natsConnectOptions({
+        sessionId: connectInfo.connectionId,
+        contextDigest: () => authorizationContexts.transportCurrent().contextDigest,
+        jwt: () => authorizationContexts.transportRoutingJwt(),
+        authorizationUsable: () => authorizationProviderCache?.transportUsable() ?? true,
+    });
+    let nc;
+    let authorizationProviderCache;
+    try {
+        nc = await transport.connect({
+            servers: selectRuntimeTransportServers(connectInfo.transports),
+            maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+            ignoreAuthErrorAbort: true,
+            timeout: 10_000,
+            inboxPrefix: connectInfo.transport.inboxPrefix,
+            authenticator: sessionOptions.authenticator,
+        });
+        const connectedNats = nc;
+        authorizationProviderCache = await AuthorizationProviderCache.attach(connectedNats, authorizationContexts.bundle().authorizationRegistry, connectInfo.transport.inboxPrefix, authorizationContexts);
+        authorizationProviderCache.start();
+        await authorizationProviderCache.waitReady();
+        await authorizationProviderCache.retainOwnContext();
+        void connectedNats.closed().finally(() => {
+            authorizationProviderCache?.stop();
+        });
+    }
+    catch (cause) {
+        authorizationProviderCache?.stop();
+        if (nc && !nc.isClosed())
+            await nc.close();
+        throw createTransportError({
+            code: "trellis.runtime.connect_failed",
+            message: "Trellis could not open the device runtime connection.",
+            hint: "Retry the connection. If it keeps failing, check Trellis transport availability.",
+            cause,
+            context: { participantId: args.participant.identity },
+        });
+    }
+    if (!nc || !authorizationProviderCache) {
+        throw new Error("Trellis device runtime connection was not established");
+    }
+    const connection = observeNatsTrellisConnection({
+        kind: "device",
+        nc,
+        availability: participantAvailability(args.participant, connectInfo.apiBindings, connectInfo.resourceBindings),
+        onTransportEvent: (event) => authorizationProviderCache.observeTransportEvent(event),
+        log: false,
+        lifecycleLog: {
+            log,
+            context: { participantId: args.participant.identity },
+        },
+    });
+    let installedAvailability = participantAvailability(args.participant, connectInfo.apiBindings, connectInfo.resourceBindings);
+    authorizationProviderCache.onOwnInvalidated(() => installConnectionAvailability(connection, participantAvailability(args.participant, {}, {}, [])));
+    authorizationProviderCache.onOwnResumed(() => {
+        installConnectionAvailability(connection, installedAvailability);
+    });
+    connection.subscribe((status) => authorizationProviderCache.observeConnectionPhase(status.phase));
+    const runtimeApi = bindApiRoutes(getParticipantRuntime(args.participant).api, connectInfo.apiBindings);
+    const stopContextRefresh = startAuthorizationContextRefresh({
+        trellisUrl: args.trellisUrl,
+        sessionId: connectInfo.connectionId,
+        auth: bootstrap.sessionAuth,
+        cache: authorizationContexts,
+        refresh: async (shouldInstall) => {
+            try {
+                const next = await fetchDeviceBootstrap({
+                    trellisUrl: args.trellisUrl,
+                    deviceIdentity: identity,
+                    rootSecret,
+                    participant: args.participant,
+                    now: deps.now,
+                    offsetState,
+                    sessionAuth: bootstrap.sessionAuth,
+                    connectionId: connectInfo.connectionId,
+                });
+                authorizationContexts.setServerClockOffsetMs(offsetState.serverClockOffsetMs);
+                const context = await authorizationContexts.prepare(next.connectInfo.authorizationContext, {
+                    bootstrapJwt: next.connectInfo.transport.jwt,
+                    bootstrapJwtExpiresAt: next.connectInfo.transport.jwtExpiresAt,
+                }, undefined, shouldInstall, undefined, () => () => {
+                    installedAvailability = participantAvailability(args.participant, next.connectInfo.apiBindings, next.connectInfo.resourceBindings);
+                    installConnectionAvailability(connection, installedAvailability);
+                    refreshApiRoutes(runtimeApi, next.connectInfo.apiBindings);
+                });
+                return context;
+            }
+            catch (error) {
+                if (error instanceof TrellisHttpError) {
+                    throw new AuthorizationContextRefreshError(error.status, error.code);
+                }
+                throw error;
+            }
+        },
+        onRefresh: async (context) => {
+            if (connection.status.phase === "connected")
+                await nc.reconnect();
+            await authorizationProviderCache.waitReady({ timeoutMs: 30_000 });
+            const generation = authorizationProviderCache.connectionGeneration();
+            await authorizationProviderCache.retainOwnCandidate(context.contextDigest, generation);
+            authorizationProviderCache.promoteOwnCandidate(context.contextDigest, generation);
+        },
+        onTerminalFailure: async () => {
+            if (!nc.isClosed())
+                await nc.close();
+        },
+    });
+    void nc.closed().then(stopContextRefresh, stopContextRefresh);
+    const trellis = new Trellis(args.participant.identity, nc, {
+        sessionKey: bootstrap.sessionAuth.sessionKey,
+        sign: bootstrap.sessionAuth.sign,
+        contextDigest: () => authorizationContexts.current().contextDigest,
+        authorizationProviderCache,
+    }, {
+        log,
+        api: runtimeApi,
+        state: getParticipantRuntime(args.participant).state,
+        connection,
+    }, connectInfo.transport.inboxPrefix);
+    const health = new ServiceHealthRuntime({
+        serviceName: args.participant.identity,
+        kind: "device",
+        instanceId,
+        contractId: connectInfo.participantId,
+        contractDigest: connectInfo.participantDigest,
+        publishIntervalMs: 30_000,
+    });
+    health.setInfo({
+        info: {
+            deploymentId,
+        },
+    });
+    health.add("nats", () => ({
+        status: nc.isClosed() ? "failed" : "ok",
+        ...(nc.isClosed() ? { summary: "NATS connection closed" } : {}),
+    }));
+    let heartbeatTimer;
+    let publishingHeartbeat = false;
+    const stopHeartbeat = () => {
+        if (heartbeatTimer !== undefined) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        }
+    };
+    const publishHeartbeat = async () => {
+        if (publishingHeartbeat) {
+            return;
+        }
+        publishingHeartbeat = true;
+        try {
+            await publishHealthHeartbeatSample({
+                nc,
+                identity: {
+                    sessionKey: bootstrap.sessionAuth.sessionKey,
+                    participantKind: "device",
+                    contractId: connectInfo.participantId,
+                    contractDigest: connectInfo.participantDigest,
+                    deploymentId,
+                    instanceId,
+                },
+                sample: await health.sample(),
+            });
+        }
+        catch (error) {
+            log.warn({ error }, "Failed to build or publish health heartbeat");
+        }
+        finally {
+            publishingHeartbeat = false;
+        }
+    };
+    await publishHeartbeat();
+    heartbeatTimer = setInterval(() => {
+        void publishHeartbeat();
+    }, health.publishIntervalMs);
+    void nc.closed().finally(stopHeartbeat);
+    let companionConnection;
+    if (bootstrap.companion) {
+        const companion = args.participant.companion;
+        if (!companion ||
+            companion.participant.identity !== bootstrap.companion.participantId) {
+            throw new Error("device bootstrap companion does not match its descriptor");
+        }
+        try {
+            const installation = bootstrap.companion.bootstrap;
+            companionConnection = await connectClientWithDeps({
+                trellisUrl: args.trellisUrl,
+                participant: companion.participant,
+                auth: {
+                    mode: "session_key",
+                    sessionKeySeed: bootstrap.companion.installationSeedBase64url,
+                    sessionId: bootstrap.companion.loginSessionId,
+                    redirectTo: new URL(args.trellisUrl).origin,
+                },
+            }, {
+                ...deps,
+                runtimeSessionKeySeed: bootstrap.companion.sessionSeedBase64url,
+                initialBootstrap: {
+                    status: "ready",
+                    serverNow: Math.floor(installation.serverNow / 1_000),
+                    serverClockOffsetMs: installation.serverNow - deps.now(),
+                    connectInfo: {
+                        connectionId: installation.runtime.connectionId,
+                        sessionId: bootstrap.companion.loginSessionId,
+                        participantId: installation.runtime.participantId,
+                        participantDigest: installation.authorization.participantDigest,
+                        transports: installation.transports,
+                        transport: {
+                            jwt: installation.routing.bootstrapJwt,
+                            jwtExpiresAt: installation.routing.bootstrapJwtExpiresAt,
+                            inboxPrefix: installation.runtime.inboxPrefix,
+                        },
+                        authorizationContext: installation.authorizationContext,
+                    },
+                    apiBindings: installation.apiBindings,
+                    resourceBindings: installation.authorization.resourceRuntime,
+                },
+            });
+        }
+        catch (error) {
+            if (bootstrap.companion.required)
+                throw error;
+            log.warn({ error }, "Optional device companion could not connect");
+        }
+    }
+    else if (args.participant.companion?.availability === "required") {
+        throw new Error("required device companion is unavailable");
+    }
+    return Object.assign(createCallerRuntime(trellis, args.participant), {
+        health,
+        companion: companionConnection,
+    });
+}
+export const TrellisDevice = {
+    connect(args) {
+        return deviceConnectResult(connectDeviceWithDeps(args, defaultDeps));
+    },
+};

package/env.d.ts

@@ -0,0 +1,2 @@
+/** Reads native service environment configuration when permission is available. */
+export declare function getEnv(key: string): string | undefined;