@oatscenter/trellis 0.100.0-rc.1

package/device/activation.js

@@ -0,0 +1,319 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { env, platform } from "node:process";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { ulid } from "ulid";
+import { deriveDeviceConfirmationCode, deriveDeviceIdentity } from "../auth.js";
+import { resumeDeviceActivationWithDeps, startDeviceActivationWithDeps, } from "../device.js";
+import { TransportError } from "../errors/index.js";
+import { base64urlDecode, base64urlEncode } from "../auth/utils.js";
+const PendingActivationStateSchema = Type.Object({
+    status: Type.Literal("pending"),
+    participantId: Type.String({ minLength: 1 }),
+    publicIdentityKey: Type.String({ minLength: 1 }),
+    instanceId: Type.String({ minLength: 1 }),
+    deploymentId: Type.String({ minLength: 1 }),
+    flowId: Type.String({ minLength: 1 }),
+    nonce: Type.String({ minLength: 1 }),
+    activationUrl: Type.String({ minLength: 1 }),
+});
+const ActivatedActivationStateSchema = Type.Object({
+    status: Type.Literal("activated"),
+    participantId: Type.String({ minLength: 1 }),
+    publicIdentityKey: Type.String({ minLength: 1 }),
+    instanceId: Type.String({ minLength: 1 }),
+    deploymentId: Type.String({ minLength: 1 }),
+    flowId: Type.String({ minLength: 1 }),
+    nonce: Type.String({ minLength: 1 }),
+    activationUrl: Type.String({ minLength: 1 }),
+});
+const LocalActivationStateSchema = Type.Union([
+    PendingActivationStateSchema,
+    ActivatedActivationStateSchema,
+]);
+const PersistedActivationStateSchema = Type.Object({
+    version: Type.Literal(1),
+    localState: LocalActivationStateSchema,
+});
+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;
+}
+function isNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isAlreadyExistsError(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function tempStatePath(statePath) {
+    return `${statePath}.tmp-${ulid()}`;
+}
+function backupStatePath(statePath) {
+    return `${statePath}.bak`;
+}
+function defaultActivationStateDir() {
+    if (platform === "win32") {
+        const base = env.LOCALAPPDATA ?? env.APPDATA;
+        if (!base) {
+            throw new Error("Could not resolve a default Trellis device state directory: LOCALAPPDATA or APPDATA is not set.");
+        }
+        return join(base, "Trellis", "device-activation");
+    }
+    const home = env.HOME;
+    if (!home) {
+        throw new Error("Could not resolve a default Trellis device state directory: HOME is not set.");
+    }
+    if (platform === "darwin") {
+        return join(home, "Library", "Application Support", "Trellis", "device-activation");
+    }
+    return join(env.XDG_STATE_HOME ?? join(home, ".local", "state"), "trellis", "device-activation");
+}
+async function hashOrigin(origin) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(origin));
+    return base64urlEncode(new Uint8Array(digest));
+}
+async function deriveStoreIdentity(args) {
+    const identity = await deriveDeviceIdentity(normalizeRootSecret(args.rootSecret));
+    return {
+        publicIdentityKey: identity.publicIdentityKey,
+    };
+}
+function parsePersistedState(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error("Stored Trellis device activation state is not valid JSON.", {
+            cause,
+        });
+    }
+    if (!Value.Check(PersistedActivationStateSchema, parsed)) {
+        throw new Error("Stored Trellis device activation state has an invalid shape.");
+    }
+    const persisted = Value.Parse(PersistedActivationStateSchema, parsed);
+    return persisted.localState;
+}
+function assertLocalStateMatchesIdentity(args) {
+    if (args.state.publicIdentityKey !== args.publicIdentityKey) {
+        throw new Error("Stored Trellis device activation state does not match the provided root secret.");
+    }
+}
+function assertLocalStateMatchesContract(args) {
+    if (args.state.participantId !== args.participantId) {
+        throw new Error("Stored Trellis device activation state belongs to another participant.");
+    }
+}
+async function resolveDeviceActivationStatePath(args) {
+    if (args.statePath) {
+        return args.statePath;
+    }
+    const { publicIdentityKey } = await deriveStoreIdentity(args);
+    const origin = new URL(args.trellisUrl).origin;
+    const originHash = await hashOrigin(origin);
+    const fileName = `activation-state-v1-${originHash}-${encodeURIComponent(args.participantId)}-${publicIdentityKey}.json`;
+    return join(args.stateDir ?? defaultActivationStateDir(), fileName);
+}
+async function openDeviceActivationStateStore(args) {
+    const { publicIdentityKey } = await deriveStoreIdentity(args);
+    const statePath = await resolveDeviceActivationStatePath(args);
+    const stateBackupPath = backupStatePath(statePath);
+    return {
+        statePath,
+        async load() {
+            for (const path of [statePath, stateBackupPath]) {
+                try {
+                    const text = new TextDecoder().decode(await readFile(path));
+                    const state = parsePersistedState(text);
+                    assertLocalStateMatchesIdentity({ state, publicIdentityKey });
+                    assertLocalStateMatchesContract({
+                        state,
+                        participantId: args.participantId,
+                    });
+                    return state;
+                }
+                catch (error) {
+                    if (isNotFoundError(error)) {
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            return null;
+        },
+        async save(state) {
+            if (!Value.Check(LocalActivationStateSchema, state)) {
+                throw new Error("Trellis device activation state has an invalid shape.");
+            }
+            assertLocalStateMatchesIdentity({ state, publicIdentityKey });
+            assertLocalStateMatchesContract({
+                state,
+                participantId: args.participantId,
+            });
+            await mkdir(dirname(statePath), { recursive: true });
+            const nextText = JSON.stringify({ version: 1, localState: state }, null, 2) +
+                "\n";
+            const nextPath = tempStatePath(statePath);
+            try {
+                await writeFile(nextPath, nextText, "utf8");
+                try {
+                    await rename(nextPath, statePath);
+                }
+                catch (error) {
+                    if (!isAlreadyExistsError(error)) {
+                        throw error;
+                    }
+                    try {
+                        await unlink(stateBackupPath);
+                    }
+                    catch (backupError) {
+                        if (!isNotFoundError(backupError)) {
+                            throw backupError;
+                        }
+                    }
+                    await rename(statePath, stateBackupPath);
+                    try {
+                        await rename(nextPath, statePath);
+                        await unlink(stateBackupPath);
+                    }
+                    catch (renameError) {
+                        try {
+                            await rename(stateBackupPath, statePath);
+                        }
+                        catch (rollbackError) {
+                            if (!isNotFoundError(rollbackError)) {
+                                throw rollbackError;
+                            }
+                        }
+                        throw renameError;
+                    }
+                }
+            }
+            catch (error) {
+                try {
+                    await unlink(nextPath);
+                }
+                catch (cleanupError) {
+                    if (!isNotFoundError(cleanupError)) {
+                        throw cleanupError;
+                    }
+                }
+                throw error;
+            }
+        },
+    };
+}
+function activatedStatus() {
+    return { status: "activated" };
+}
+function createActivatedLocalState(localState) {
+    return {
+        ...localState,
+        status: "activated",
+    };
+}
+async function createActivationRequiredStatus(args) {
+    const session = args.localState?.status === "pending"
+        ? await resumeDeviceActivationWithDeps({
+            trellisUrl: args.checkArgs.trellisUrl,
+            participant: args.checkArgs.participant,
+            provisioningSecret: args.checkArgs.provisioningSecret,
+            rootSecret: args.checkArgs.rootSecret,
+            localState: args.localState,
+        }, { now: () => Date.now() })
+        : await startDeviceActivationWithDeps({
+            trellisUrl: args.checkArgs.trellisUrl,
+            participant: args.checkArgs.participant,
+            provisioningSecret: args.checkArgs.provisioningSecret,
+            rootSecret: args.checkArgs.rootSecret,
+        }, { now: () => Date.now() });
+    if (args.localState?.status !== "pending") {
+        await args.store.save(session.localState);
+    }
+    let completedState = null;
+    const identity = await deriveDeviceIdentity(normalizeRootSecret(args.checkArgs.rootSecret));
+    const confirmationCode = await deriveDeviceConfirmationCode({
+        activationKey: identity.activationKey,
+        publicIdentityKey: identity.publicIdentityKey,
+        nonce: session.localState.nonce,
+    });
+    let completionPromise = null;
+    const finish = async (nextState) => {
+        if (completedState) {
+            return activatedStatus();
+        }
+        if (completionPromise) {
+            return await completionPromise;
+        }
+        completionPromise = (async () => {
+            const nextCompletedState = await nextState();
+            await args.store.save(nextCompletedState);
+            completedState = nextCompletedState;
+            return activatedStatus();
+        })();
+        try {
+            return await completionPromise;
+        }
+        catch (error) {
+            completionPromise = null;
+            throw error;
+        }
+    };
+    return {
+        status: "activation_required",
+        activationUrl: session.activationUrl,
+        confirmationCode,
+        waitForOnlineApproval(opts) {
+            return finish(() => session.waitForOnlineApproval(opts));
+        },
+        acceptConfirmationCode(code) {
+            return finish(() => session.acceptConfirmationCode(code));
+        },
+    };
+}
+/**
+ * Reports native device activation status and hides local activation persistence details.
+ */
+export async function checkDeviceActivation(args) {
+    const store = await openDeviceActivationStateStore({
+        trellisUrl: args.trellisUrl,
+        rootSecret: args.rootSecret,
+        participantId: args.participant.identity,
+        stateDir: args.stateDir,
+        statePath: args.statePath,
+    });
+    const localState = await store.load();
+    try {
+        return await createActivationRequiredStatus({
+            checkArgs: args,
+            store,
+            localState,
+        });
+    }
+    catch (error) {
+        if (error instanceof TransportError &&
+            error.code === "device_activation_unavailable" &&
+            error.getContext().status === "ready") {
+            if (localState?.status === "pending") {
+                await store.save(createActivatedLocalState(localState));
+            }
+            return activatedStatus();
+        }
+        if (error instanceof TransportError &&
+            error.code === "device_activation_unavailable" &&
+            error.getContext().status === "not_ready") {
+            return { status: "not_ready", reason: "activation_rejected" };
+        }
+        throw error;
+    }
+}

package/device.d.ts

@@ -0,0 +1,80 @@
+export { checkDeviceActivation } from "./device/activation.ts";
+export type { CheckDeviceActivationArgs, TrellisDeviceActivatedStatus, TrellisDeviceActivationRequiredStatus, TrellisDeviceActivationStatus, TrellisDeviceNotReadyStatus, } from "./device/activation.ts";
+import { AsyncResult, UnexpectedError } from "@oatscenter/result";
+import { type ConnectedTrellisClient } from "./client_connect.ts";
+import { type ServiceHealth } from "./service/runtime/health.ts";
+import { type LoggerLike } from "./globals.ts";
+import { TransportError } from "./errors/index.ts";
+import { type CallerRuntime } from "./caller.ts";
+import { type GeneratedParticipant } from "./participant_runtime/participant.ts";
+type DeviceContract = GeneratedParticipant;
+export type TrellisDeviceConnection<TContract extends DeviceContract = DeviceContract> = CallerRuntime<TContract> & {
+    readonly health: ServiceHealth;
+} & (TContract extends {
+    companion: {
+        participant: infer TChild extends GeneratedParticipant;
+        availability: infer TAvailability;
+    };
+} ? {
+    readonly companion: TAvailability extends "required" ? ConnectedTrellisClient<TChild> : ConnectedTrellisClient<TChild> | undefined;
+} : {
+    readonly companion?: never;
+});
+export type TrellisDevicePendingActivationState = {
+    status: "pending";
+    participantId: string;
+    publicIdentityKey: string;
+    instanceId: string;
+    deploymentId: string;
+    flowId: string;
+    nonce: string;
+    activationUrl: string;
+};
+export type TrellisDeviceActivatedActivationState = {
+    status: "activated";
+    participantId: string;
+    publicIdentityKey: string;
+    instanceId: string;
+    deploymentId: string;
+    flowId: string;
+    nonce: string;
+    activationUrl: string;
+};
+export type TrellisDeviceLocalActivationState = TrellisDevicePendingActivationState | TrellisDeviceActivatedActivationState;
+export type TrellisDeviceActivationSession<TState extends TrellisDeviceLocalActivationState = TrellisDeviceLocalActivationState> = {
+    activationUrl: string;
+    localState: TState;
+    waitForOnlineApproval(opts?: {
+        signal?: AbortSignal;
+    }): Promise<TrellisDeviceActivatedActivationState>;
+    acceptConfirmationCode(code: string): Promise<TrellisDeviceActivatedActivationState>;
+};
+export type TrellisDeviceActivationArgs<TContract extends DeviceContract = DeviceContract> = {
+    trellisUrl: string;
+    participant: TContract;
+    rootSecret: Uint8Array | string;
+    provisioningSecret?: string;
+};
+/** Provisioned device identity and exact deployment participant binding. */
+export type TrellisDeviceProvisionedIdentity = {
+    deploymentId: string;
+    instanceId: string;
+    principalId: string;
+    participantId: string;
+    participantDigest: string;
+    participantNeedsDigest: string;
+    provisioningSecret?: string;
+    expectedSecretVersion?: number;
+};
+export type TrellisDeviceResumeActivationArgs<TContract extends DeviceContract = DeviceContract> = TrellisDeviceActivationArgs<TContract> & {
+    localState: TrellisDeviceLocalActivationState;
+};
+export type TrellisDeviceConnectArgs<TContract extends DeviceContract = DeviceContract> = {
+    trellisUrl: string;
+    participant: TContract;
+    rootSecret: Uint8Array | string;
+    log?: LoggerLike | false;
+};
+export declare const TrellisDevice: {
+    connect<TContract extends DeviceContract>(args: TrellisDeviceConnectArgs<TContract>): AsyncResult<TrellisDeviceConnection<TContract>, TransportError | UnexpectedError>;
+};