@qlever-llc/trellis 0.7.0 → 0.8.0-rc.3

package/script/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../device.ts"],"names":[],"mappings":"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"}

package/script/device.js

@@ -0,0 +1,550 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrellisDevice = void 0;
+exports.startDeviceActivationWithDeps = startDeviceActivationWithDeps;
+exports.resumeDeviceActivationWithDeps = resumeDeviceActivationWithDeps;
+exports.connectDeviceWithDeps = connectDeviceWithDeps;
+const nats_core_1 = require("@nats-io/nats-core");
+const result_1 = require("@qlever-llc/result");
+const mod_ts_1 = require("./contract_support/mod.js");
+const device_activation_ts_1 = require("./auth/device_activation.js");
+const keys_ts_1 = require("./auth/keys.js");
+const utils_ts_1 = require("./auth/utils.js");
+const time_ts_1 = require("./auth/time.js");
+const session_auth_ts_1 = require("./auth/session_auth.js");
+const runtime_transport_ts_1 = require("./runtime_transport.js");
+const health_ts_1 = require("./health.js");
+const trellis_ts_1 = require("./trellis.js");
+const globals_ts_1 = require("./globals.js");
+const index_ts_1 = require("./errors/index.js");
+const typebox_1 = require("typebox");
+const value_1 = require("typebox/value");
+const connection_ts_1 = require("./connection.js");
+function deviceConnectResult(promise) {
+    return result_1.AsyncResult.from(promise.then((value) => result_1.Result.ok(value), (cause) => result_1.Result.err(cause instanceof index_ts_1.TransportError
+        ? cause
+        : new result_1.UnexpectedError({ cause }))));
+}
+const ClientTransportEndpointsSchema = typebox_1.Type.Object({
+    natsServers: typebox_1.Type.Array(typebox_1.Type.String({ minLength: 1 }), { minItems: 1 }),
+});
+const ClientTransportsSchema = typebox_1.Type.Object({
+    native: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+    websocket: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+});
+const DeviceBootstrapReadySchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("ready"),
+    connectInfo: typebox_1.Type.Object({
+        instanceId: typebox_1.Type.String({ minLength: 1 }),
+        deploymentId: typebox_1.Type.String({ minLength: 1 }),
+        contractId: typebox_1.Type.String({ minLength: 1 }),
+        contractDigest: typebox_1.Type.String({ minLength: 1 }),
+        transports: ClientTransportsSchema,
+        transport: typebox_1.Type.Object({
+            sentinel: typebox_1.Type.Object({
+                jwt: typebox_1.Type.String({ minLength: 1 }),
+                seed: typebox_1.Type.String({ minLength: 1 }),
+            }),
+        }),
+        auth: typebox_1.Type.Object({
+            mode: typebox_1.Type.Literal("device_identity"),
+            iatSkewSeconds: typebox_1.Type.Integer({ minimum: 1 }),
+        }),
+    }),
+});
+const DeviceBootstrapActivationRequiredSchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("activation_required"),
+});
+const DeviceBootstrapNotReadySchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("not_ready"),
+    reason: typebox_1.Type.String({ minLength: 1 }),
+});
+function normalizeRootSecret(rootSecret) {
+    if (typeof rootSecret === "string") {
+        const decoded = (0, utils_ts_1.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;
+}
+async function signIdentityBytes(identitySeed, data) {
+    const privateKey = await (0, keys_ts_1.importEd25519PrivateKeyFromSeedBase64url)((0, utils_ts_1.base64urlEncode)(identitySeed));
+    return new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, (0, utils_ts_1.toArrayBuffer)(data)));
+}
+function createDeviceNatsAuthTokenAuthenticator(args) {
+    return () => {
+        const iat = (0, time_ts_1.correctedIatSeconds)(args.now(), args.getServerClockOffsetMs());
+        const sig = (0, keys_ts_1.signEd25519SeedSha256)(args.identitySeed, new TextEncoder().encode(`nats-connect:${(0, session_auth_ts_1.buildNatsConnectSignaturePayload)(iat, args.contractDigest)}`));
+        return {
+            auth_token: JSON.stringify({
+                v: 1,
+                sessionKey: args.publicIdentityKey,
+                iat,
+                sig: (0, utils_ts_1.base64urlEncode)(new Uint8Array(sig)),
+                contractDigest: args.contractDigest,
+            }),
+        };
+    };
+}
+const defaultDeps = {
+    loadTransport: runtime_transport_ts_1.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 index_ts_1.TransportError({
+        code: args.code,
+        message: args.message,
+        hint: args.hint,
+        cause: args.cause,
+        context: {
+            ...(args.context ?? {}),
+            ...(args.cause === undefined ? {} : transportCauseContext(args.cause)),
+        },
+    });
+}
+function assertBootstrapContractMatches(args) {
+    if (args.connectInfo.contractId !== args.contractId ||
+        args.connectInfo.contractDigest !== args.contractDigest) {
+        throw createTransportError({
+            code: "trellis.bootstrap.contract_mismatch",
+            message: "Trellis returned connection details for a different device contract.",
+            hint: "Retry the connection. If it keeps happening, check the requested device contract and Trellis activation state.",
+            context: {
+                requestedContractId: args.contractId,
+                requestedContractDigest: args.contractDigest,
+                returnedContractId: args.connectInfo.contractId,
+                returnedContractDigest: args.connectInfo.contractDigest,
+            },
+        });
+    }
+}
+async function readJsonResponse(response, args) {
+    try {
+        return await response.json();
+    }
+    catch (cause) {
+        throw createTransportError({
+            ...args,
+            cause,
+        });
+    }
+}
+function parseResponseRecord(text) {
+    if (text.length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveDeviceLogger(log) {
+    if (log === false) {
+        return globals_ts_1.logger;
+    }
+    return log ?? globals_ts_1.logger;
+}
+async function readResponseReason(response) {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.reason === "string" && parsed.reason.length > 0) {
+            return parsed.reason;
+        }
+    }
+    catch {
+        return text;
+    }
+    return text;
+}
+function createActivationRequiredTransportError(context) {
+    return createTransportError({
+        code: "trellis.bootstrap.activation_required",
+        message: "Trellis requires device activation before connecting.",
+        hint: "Start or resume device activation, then retry the runtime connection after activation completes.",
+        context,
+    });
+}
+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.contractDigest !== args.contractDigest) {
+        throw createTransportError({
+            code: "trellis.device.activation_state_contract_mismatch",
+            message: "Local device activation state does not match the requested device contract.",
+            hint: "Use activation state for the same device contract, or start activation again for this contract digest.",
+            context: {
+                stateContractDigest: args.localState.contractDigest,
+                contractDigest: args.contractDigest,
+            },
+        });
+    }
+}
+async function createActivationSession(args) {
+    assertActivationStateMatchesIdentity({
+        localState: args.localState,
+        publicIdentityKey: args.identity.publicIdentityKey,
+    });
+    assertActivationStateMatchesContract({
+        localState: args.localState,
+        contractDigest: args.contractDigest,
+    });
+    const activatedState = createActivatedLocalState(args.localState);
+    return {
+        activationUrl: args.localState.activationUrl,
+        localState: args.localState,
+        waitForOnlineApproval: async (opts) => {
+            if (args.localState.status === "activated") {
+                return activatedState;
+            }
+            await (0, device_activation_ts_1.waitForDeviceActivation)({
+                trellisUrl: args.trellisUrl,
+                publicIdentityKey: args.identity.publicIdentityKey,
+                nonce: args.localState.nonce,
+                identitySeed: args.identity.identitySeed,
+                contractDigest: args.contractDigest,
+                signal: opts?.signal,
+            });
+            return activatedState;
+        },
+        acceptConfirmationCode: async (code) => {
+            if (args.localState.status === "activated") {
+                return activatedState;
+            }
+            const ok = await (0, device_activation_ts_1.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) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const requestStartedAtMs = args.now();
+        const request = await (0, device_activation_ts_1.signDeviceWaitRequest)({
+            publicIdentityKey: args.publicIdentityKey,
+            nonce: "connect-info",
+            identitySeed: args.identitySeed,
+            contractDigest: args.contractDigest,
+            iat: (0, time_ts_1.correctedIatSeconds)(requestStartedAtMs, args.offsetState.serverClockOffsetMs),
+        });
+        const bootstrapRequest = {
+            publicIdentityKey: request.publicIdentityKey,
+            contractDigest: request.contractDigest,
+            iat: request.iat,
+            sig: request.sig,
+        };
+        const response = await fetch(new URL("/auth/devices/connect-info", args.trellisUrl), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(bootstrapRequest),
+        });
+        const responseReceivedAtMs = args.now();
+        if (!response.ok) {
+            const responseText = await response.text();
+            const parsed = parseResponseRecord(responseText);
+            const reason = typeof parsed?.reason === "string"
+                ? parsed.reason
+                : responseText;
+            const serverNow = typeof parsed?.serverNow === "number"
+                ? parsed.serverNow
+                : null;
+            if (attempt === 0 &&
+                response.status === 400 &&
+                reason === "iat_out_of_range" &&
+                serverNow !== null) {
+                args.offsetState.serverClockOffsetMs = (0, time_ts_1.estimateMidpointClockOffsetMs)({
+                    requestStartedAtMs,
+                    responseReceivedAtMs,
+                    serverNowSeconds: serverNow,
+                });
+                continue;
+            }
+            if (response.status === 404 &&
+                (reason === "unknown_device" || reason === "activation_required")) {
+                return { status: "activation_required" };
+            }
+            throw createTransportError({
+                code: "trellis.bootstrap.failed",
+                message: "Trellis could not prepare the device session.",
+                hint: "Retry the connection. If it keeps failing, check Trellis availability and device activation state.",
+                context: {
+                    trellisUrl: args.trellisUrl,
+                    status: response.status,
+                    reason,
+                },
+            });
+        }
+        const payload = await readJsonResponse(response, {
+            code: "trellis.bootstrap.invalid_response",
+            message: "Trellis returned an invalid bootstrap response.",
+            hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+            context: { trellisUrl: args.trellisUrl },
+        });
+        if (payload && typeof payload === "object" &&
+            typeof payload.serverNow === "number") {
+            args.offsetState.serverClockOffsetMs = (0, time_ts_1.estimateMidpointClockOffsetMs)({
+                requestStartedAtMs,
+                responseReceivedAtMs,
+                serverNowSeconds: payload.serverNow,
+            });
+        }
+        if (value_1.Value.Check(DeviceBootstrapReadySchema, payload))
+            return payload;
+        if (value_1.Value.Check(DeviceBootstrapActivationRequiredSchema, payload)) {
+            return payload;
+        }
+        if (value_1.Value.Check(DeviceBootstrapNotReadySchema, payload))
+            return payload;
+        throw createTransportError({
+            code: "trellis.bootstrap.invalid_response",
+            message: "Trellis returned an invalid bootstrap response.",
+            hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+            context: { trellisUrl: args.trellisUrl },
+        });
+    }
+    throw createTransportError({
+        code: "trellis.bootstrap.time_sync_failed",
+        message: "Trellis could not confirm the device time window.",
+        hint: "Retry the connection. If it keeps happening, check the device and Trellis clocks.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+}
+async function startDeviceActivationWithDeps(args, _deps) {
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await (0, device_activation_ts_1.deriveDeviceIdentity)(rootSecret);
+    const nonce = crypto.randomUUID();
+    const payload = await (0, device_activation_ts_1.buildDeviceActivationPayload)({
+        activationKey: identity.activationKey,
+        publicIdentityKey: identity.publicIdentityKey,
+        nonce,
+    });
+    const activation = await (0, device_activation_ts_1.startDeviceActivationRequest)({
+        trellisUrl: args.trellisUrl,
+        payload,
+    });
+    return await createActivationSession({
+        trellisUrl: args.trellisUrl,
+        contractDigest: args.contract.CONTRACT_DIGEST,
+        identity,
+        localState: {
+            status: "pending",
+            contractDigest: args.contract.CONTRACT_DIGEST,
+            publicIdentityKey: identity.publicIdentityKey,
+            instanceId: activation.instanceId,
+            deploymentId: activation.deploymentId,
+            nonce,
+            activationUrl: activation.activationUrl,
+        },
+    });
+}
+async function resumeDeviceActivationWithDeps(args, _deps) {
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await (0, device_activation_ts_1.deriveDeviceIdentity)(rootSecret);
+    return await createActivationSession({
+        trellisUrl: args.trellisUrl,
+        contractDigest: args.contract.CONTRACT_DIGEST,
+        identity,
+        localState: args.localState,
+    });
+}
+async function connectDeviceWithDeps(args, deps) {
+    const log = resolveDeviceLogger(args.log);
+    const rootSecret = normalizeRootSecret(args.rootSecret);
+    const identity = await (0, device_activation_ts_1.deriveDeviceIdentity)(rootSecret);
+    const contractDigest = args.contract.CONTRACT_DIGEST;
+    const offsetState = { serverClockOffsetMs: 0 };
+    const bootstrap = await fetchDeviceBootstrap({
+        trellisUrl: args.trellisUrl,
+        publicIdentityKey: identity.publicIdentityKey,
+        identitySeed: identity.identitySeed,
+        contractDigest,
+        now: deps.now,
+        offsetState,
+    });
+    if (bootstrap.status === "activation_required") {
+        throw createActivationRequiredTransportError({
+            publicIdentityKey: identity.publicIdentityKey,
+            contractId: args.contract.CONTRACT_ID,
+        });
+    }
+    if (bootstrap.status === "not_ready") {
+        throw createTransportError({
+            code: "trellis.bootstrap.not_ready",
+            message: "Trellis is not ready to connect this device.",
+            hint: "Wait for the device to be activated and the requested deployment to become available, then try again.",
+            context: { reason: bootstrap.reason },
+        });
+    }
+    const connectInfo = bootstrap.connectInfo;
+    assertBootstrapContractMatches({
+        contractId: args.contract.CONTRACT_ID,
+        contractDigest,
+        connectInfo,
+    });
+    const transport = await deps.loadTransport();
+    let nc;
+    try {
+        nc = await transport.connect({
+            servers: (0, runtime_transport_ts_1.selectRuntimeTransportServers)(connectInfo.transports),
+            maxReconnectAttempts: runtime_transport_ts_1.DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+            inboxPrefix: `_INBOX.${identity.publicIdentityKey.slice(0, 16)}`,
+            authenticator: [
+                createDeviceNatsAuthTokenAuthenticator({
+                    publicIdentityKey: identity.publicIdentityKey,
+                    identitySeed: identity.identitySeed,
+                    contractDigest,
+                    now: deps.now,
+                    getServerClockOffsetMs: () => offsetState.serverClockOffsetMs,
+                }),
+                (0, nats_core_1.jwtAuthenticator)(connectInfo.transport.sentinel.jwt, new TextEncoder().encode(connectInfo.transport.sentinel.seed)),
+            ],
+        });
+    }
+    catch (cause) {
+        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: { contractId: args.contract.CONTRACT_ID },
+        });
+    }
+    const connection = (0, connection_ts_1.observeNatsTrellisConnection)({
+        kind: "device",
+        nc,
+        log: false,
+        lifecycleLog: {
+            log,
+            context: { contractId: args.contract.CONTRACT_ID },
+        },
+    });
+    const trellis = new trellis_ts_1.Trellis(args.contract.CONTRACT_ID, nc, {
+        sessionKey: identity.publicIdentityKey,
+        sign: (data) => signIdentityBytes(identity.identitySeed, data),
+    }, {
+        log,
+        api: args.contract.API.trellis,
+        state: args.contract[mod_ts_1.CONTRACT_STATE_METADATA],
+        connection,
+    });
+    const health = new health_ts_1.ServiceHealth({
+        serviceName: args.contract.CONTRACT?.displayName ??
+            args.contract.CONTRACT_ID,
+        kind: "device",
+        instanceId: connectInfo.instanceId,
+        contractId: connectInfo.contractId,
+        contractDigest: connectInfo.contractDigest,
+        publishIntervalMs: 30_000,
+    });
+    health.setInfo({
+        info: {
+            deploymentId: connectInfo.deploymentId,
+        },
+    });
+    health.add("nats", () => ({
+        status: nc.isClosed() ? "failed" : "ok",
+        ...(nc.isClosed() ? { summary: "NATS connection closed" } : {}),
+    }));
+    const heartbeatEventEnabled = Boolean(args.contract.API.trellis.events?.["Health.Heartbeat"]);
+    let heartbeatTimer;
+    let publishingHeartbeat = false;
+    const stopHeartbeat = () => {
+        if (heartbeatTimer !== undefined) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        }
+    };
+    const publishHeartbeat = async () => {
+        if (!heartbeatEventEnabled || publishingHeartbeat) {
+            return;
+        }
+        publishingHeartbeat = true;
+        try {
+            const heartbeat = await health.heartbeat();
+            await trellis.publish("Health.Heartbeat", heartbeat);
+        }
+        finally {
+            publishingHeartbeat = false;
+        }
+    };
+    if (heartbeatEventEnabled) {
+        await publishHeartbeat();
+        heartbeatTimer = setInterval(() => {
+            void publishHeartbeat();
+        }, health.publishIntervalMs);
+        void nc.closed().finally(stopHeartbeat);
+    }
+    return {
+        request: trellis.request.bind(trellis),
+        publish: trellis.publish.bind(trellis),
+        event: trellis.event.bind(trellis),
+        operation: trellis.operation.bind(trellis),
+        transfer: trellis.transfer.bind(trellis),
+        state: trellis.state,
+        name: trellis.name,
+        timeout: trellis.timeout,
+        stream: trellis.stream,
+        api: trellis.api,
+        connection: trellis.connection,
+        natsConnection: trellis.natsConnection,
+        health,
+    };
+}
+exports.TrellisDevice = {
+    connect(args) {
+        return deviceConnectResult(connectDeviceWithDeps(args, defaultDeps));
+    },
+};

package/script/errors/AuthError.d.ts

@@ -0,0 +1,30 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.ts";
+export declare const AuthErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"AuthError">;
+    message: Type.TString;
+    reason: Type.TUnion<[Type.TLiteral<"invalid_request">, Type.TLiteral<"missing_session_key">, Type.TLiteral<"missing_proof">, Type.TLiteral<"session_not_found">, Type.TLiteral<"session_expired">, Type.TLiteral<"invalid_signature">, Type.TLiteral<"user_not_found">, Type.TLiteral<"user_inactive">, Type.TLiteral<"unknown_device">, Type.TLiteral<"device_deployment_not_found">, Type.TLiteral<"device_deployment_disabled">, Type.TLiteral<"device_activation_revoked">, Type.TLiteral<"unknown_service">, Type.TLiteral<"service_disabled">, Type.TLiteral<"iat_out_of_range">, Type.TLiteral<"invalid_binding_token">, Type.TLiteral<"session_corrupted">, Type.TLiteral<"session_already_bound">, Type.TLiteral<"authtoken_already_used">, Type.TLiteral<"oauth_session_key_mismatch">, Type.TLiteral<"service_role_on_user">, Type.TLiteral<"reply_subject_mismatch">, Type.TLiteral<"insufficient_permissions">, Type.TLiteral<"forbidden">, Type.TLiteral<"missing_flow_id">, Type.TLiteral<"device_activation_flow_not_found">, Type.TLiteral<"device_activation_flow_expired">, Type.TLiteral<"device_activation_rejected">, Type.TLiteral<"device_identity_key_mismatch">, Type.TLiteral<"invalid_device_qr_mac">]>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type AuthErrorData = Static<typeof AuthErrorDataSchema>;
+/**
+ * Error for authentication and authorization failures.
+ */
+export declare class AuthError extends TrellisError<AuthErrorData> {
+    readonly name: "AuthError";
+    readonly reason: AuthErrorData["reason"];
+    constructor(options: ErrorOptions & {
+        reason: AuthErrorData["reason"];
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): AuthErrorData;
+}
+//# sourceMappingURL=AuthError.d.ts.map

package/script/errors/AuthError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthError.d.ts","sourceRoot":"","sources":["../../../errors/AuthError.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,mBAAmB;;;;;;;EAsC9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY,CAAC,aAAa,CAAC;IACxD,SAAkB,IAAI,EAAG,WAAW,CAAU;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;gBAGvC,OAAO,EAAE,YAAY,GAAG;QACtB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb;IAOH;;;;OAIG;IACM,cAAc,IAAI,aAAa;CAOzC"}

package/script/errors/AuthError.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthError = exports.AuthErrorDataSchema = void 0;
+const typebox_1 = __importDefault(require("typebox"));
+const TrellisError_ts_1 = require("./TrellisError.js");
+exports.AuthErrorDataSchema = typebox_1.default.Object({
+    id: typebox_1.default.String(),
+    type: typebox_1.default.Literal("AuthError"),
+    message: typebox_1.default.String(),
+    reason: typebox_1.default.Union([
+        typebox_1.default.Literal("invalid_request"),
+        typebox_1.default.Literal("missing_session_key"),
+        typebox_1.default.Literal("missing_proof"),
+        typebox_1.default.Literal("session_not_found"),
+        typebox_1.default.Literal("session_expired"),
+        typebox_1.default.Literal("invalid_signature"),
+        typebox_1.default.Literal("user_not_found"),
+        typebox_1.default.Literal("user_inactive"),
+        typebox_1.default.Literal("unknown_device"),
+        typebox_1.default.Literal("device_deployment_not_found"),
+        typebox_1.default.Literal("device_deployment_disabled"),
+        typebox_1.default.Literal("device_activation_revoked"),
+        typebox_1.default.Literal("unknown_service"),
+        typebox_1.default.Literal("service_disabled"),
+        typebox_1.default.Literal("iat_out_of_range"),
+        typebox_1.default.Literal("invalid_binding_token"),
+        typebox_1.default.Literal("session_corrupted"),
+        typebox_1.default.Literal("session_already_bound"),
+        typebox_1.default.Literal("authtoken_already_used"),
+        typebox_1.default.Literal("oauth_session_key_mismatch"),
+        typebox_1.default.Literal("service_role_on_user"),
+        typebox_1.default.Literal("reply_subject_mismatch"),
+        typebox_1.default.Literal("insufficient_permissions"),
+        typebox_1.default.Literal("forbidden"),
+        typebox_1.default.Literal("missing_flow_id"),
+        typebox_1.default.Literal("device_activation_flow_not_found"),
+        typebox_1.default.Literal("device_activation_flow_expired"),
+        typebox_1.default.Literal("device_activation_rejected"),
+        typebox_1.default.Literal("device_identity_key_mismatch"),
+        typebox_1.default.Literal("invalid_device_qr_mac"),
+    ]),
+    context: typebox_1.default.Optional(typebox_1.default.Record(typebox_1.default.String(), typebox_1.default.Unknown())),
+    traceId: typebox_1.default.Optional(typebox_1.default.String()),
+});
+/**
+ * Error for authentication and authorization failures.
+ */
+class AuthError extends TrellisError_ts_1.TrellisError {
+    constructor(options) {
+        const { reason, ...baseOptions } = options;
+        super(`Auth failed: ${reason}`, baseOptions);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "AuthError"
+        });
+        Object.defineProperty(this, "reason", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.reason = reason;
+    }
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            reason: this.reason,
+        };
+    }
+}
+exports.AuthError = AuthError;