@nextera.one/axis-server-sdk 1.2.0 → 1.2.1

package/dist/index.js

@@ -33,6 +33,7 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
 // src/index.ts
 var index_exports = {};
@@ -41,8 +42,13 @@ __export(index_exports, {
   ATS1_SCHEMA: () => ATS1_SCHEMA,
   AXIS_MAGIC: () => import_axis_protocol2.AXIS_MAGIC,
   AXIS_OPCODES: () => AXIS_OPCODES,
+  AXIS_UPLOAD_FILE_STORE: () => AXIS_UPLOAD_FILE_STORE,
+  AXIS_UPLOAD_RECEIPT_SIGNER: () => AXIS_UPLOAD_RECEIPT_SIGNER,
+  AXIS_UPLOAD_SESSION_STORE: () => AXIS_UPLOAD_SESSION_STORE,
   AXIS_VERSION: () => import_axis_protocol2.AXIS_VERSION,
   Ats1Codec: () => ats1_exports,
+  AxisFilesDownloadHandler: () => AxisFilesDownloadHandler,
+  AxisFilesFinalizeHandler: () => AxisFilesFinalizeHandler,
   AxisFrameZ: () => AxisFrameZ,
   AxisIdDto: () => AxisIdDto,
   AxisPacketTags: () => T,
@@ -55,6 +61,7 @@ __export(index_exports, {
   DEFAULT_CONTRACTS: () => DEFAULT_CONTRACTS,
   DEFAULT_TIMEOUT: () => DEFAULT_TIMEOUT,
   Decision: () => Decision,
+  DiskUploadFileStore: () => DiskUploadFileStore,
   ERR_BAD_SIGNATURE: () => import_axis_protocol2.ERR_BAD_SIGNATURE,
   ERR_CONTRACT_VIOLATION: () => import_axis_protocol2.ERR_CONTRACT_VIOLATION,
   ERR_INVALID_PACKET: () => import_axis_protocol2.ERR_INVALID_PACKET,
@@ -66,14 +73,18 @@ __export(index_exports, {
   FLAG_HAS_WITNESS: () => import_axis_protocol2.FLAG_HAS_WITNESS,
   HANDLER_METADATA_KEY: () => HANDLER_METADATA_KEY,
   Handler: () => Handler,
+  INTENT_BODY_KEY: () => INTENT_BODY_KEY,
   INTENT_METADATA_KEY: () => INTENT_METADATA_KEY,
   INTENT_REQUIREMENTS: () => INTENT_REQUIREMENTS,
   INTENT_ROUTES_KEY: () => INTENT_ROUTES_KEY,
   INTENT_SENSITIVITY_MAP: () => INTENT_SENSITIVITY_MAP,
+  INTENT_SENSORS_KEY: () => INTENT_SENSORS_KEY,
   INTENT_TIMEOUTS: () => INTENT_TIMEOUTS,
   Intent: () => Intent,
+  IntentBody: () => IntentBody,
   IntentRouter: () => IntentRouter,
   IntentSensitivity: () => IntentSensitivity,
+  IntentSensors: () => IntentSensors,
   MAX_BODY_LEN: () => import_axis_protocol2.MAX_BODY_LEN,
   MAX_FRAME_LEN: () => import_axis_protocol2.MAX_FRAME_LEN,
   MAX_HDR_LEN: () => import_axis_protocol2.MAX_HDR_LEN,
@@ -245,8 +256,26 @@ function Intent(action, options) {
   };
 }
 
-// src/decorators/tlv-field.decorator.ts
+// src/decorators/intent-body.decorator.ts
 var import_reflect_metadata2 = require("reflect-metadata");
+var INTENT_BODY_KEY = "axis:intent:body";
+function IntentBody(decoder) {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(INTENT_BODY_KEY, decoder, target, propertyKey);
+  };
+}
+
+// src/decorators/intent-sensors.decorator.ts
+var import_reflect_metadata3 = require("reflect-metadata");
+var INTENT_SENSORS_KEY = "axis:intent:sensors";
+function IntentSensors(sensors) {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(INTENT_SENSORS_KEY, sensors, target, propertyKey);
+  };
+}
+
+// src/decorators/tlv-field.decorator.ts
+var import_reflect_metadata4 = require("reflect-metadata");
 var TLV_FIELDS_KEY = "axis:tlv:fields";
 var TLV_VALIDATORS_KEY = "axis:tlv:validators";
 function TlvField(tag, options) {
@@ -304,7 +333,7 @@ function TlvRange(min, max, message) {
 }
 
 // src/decorators/dto-schema.util.ts
-var import_reflect_metadata3 = require("reflect-metadata");
+var import_reflect_metadata5 = require("reflect-metadata");
 
 // src/core/tlv.ts
 var import_axis_protocol = require("@nextera.one/axis-protocol");
@@ -405,7 +434,7 @@ __decorateClass([
 ], AxisIdDto.prototype, "id", 2);
 
 // src/base/axis-partial-type.ts
-var import_reflect_metadata4 = require("reflect-metadata");
+var import_reflect_metadata6 = require("reflect-metadata");
 function AxisPartialType(BaseDto) {
   class PartialDto extends BaseDto {
   }
@@ -452,10 +481,145 @@ __decorateClass([
 
 // src/engine/intent.router.ts
 var import_common2 = require("@nestjs/common");
+
+// src/sensor/axis-sensor.ts
+var Decision = /* @__PURE__ */ ((Decision2) => {
+  Decision2["ALLOW"] = "ALLOW";
+  Decision2["DENY"] = "DENY";
+  Decision2["THROTTLE"] = "THROTTLE";
+  Decision2["FLAG"] = "FLAG";
+  return Decision2;
+})(Decision || {});
+function normalizeSensorDecision(sensorDecision) {
+  if ("action" in sensorDecision) {
+    switch (sensorDecision.action) {
+      case "ALLOW":
+        return {
+          allow: true,
+          riskScore: 0,
+          reasons: [],
+          meta: sensorDecision.meta
+        };
+      case "DENY":
+        return {
+          allow: false,
+          riskScore: 100,
+          reasons: [sensorDecision.code, sensorDecision.reason].filter(
+            Boolean
+          ),
+          meta: sensorDecision.meta,
+          retryAfterMs: sensorDecision.retryAfterMs
+        };
+      case "THROTTLE":
+        return {
+          allow: false,
+          riskScore: 50,
+          reasons: ["RATE_LIMIT"],
+          retryAfterMs: sensorDecision.retryAfterMs,
+          meta: sensorDecision.meta
+        };
+      case "FLAG":
+        return {
+          allow: true,
+          riskScore: sensorDecision.scoreDelta,
+          reasons: sensorDecision.reasons,
+          meta: sensorDecision.meta
+        };
+    }
+  }
+  return {
+    allow: sensorDecision.allow,
+    riskScore: sensorDecision.riskScore,
+    reasons: sensorDecision.reasons,
+    tags: sensorDecision.tags,
+    meta: sensorDecision.meta,
+    tighten: sensorDecision.tighten,
+    retryAfterMs: sensorDecision.retryAfterMs
+  };
+}
+var SensorDecisions = {
+  allow(meta, tags) {
+    return {
+      decision: "ALLOW" /* ALLOW */,
+      allow: true,
+      riskScore: 0,
+      reasons: [],
+      tags,
+      meta
+    };
+  },
+  deny(code, reason, meta) {
+    return {
+      decision: "DENY" /* DENY */,
+      allow: false,
+      riskScore: 100,
+      code,
+      reasons: [code, reason].filter(Boolean),
+      meta
+    };
+  },
+  throttle(retryAfterMs, meta) {
+    return {
+      decision: "THROTTLE" /* THROTTLE */,
+      allow: false,
+      riskScore: 50,
+      retryAfterMs,
+      code: "RATE_LIMIT",
+      reasons: ["RATE_LIMIT"],
+      meta
+    };
+  },
+  flag(scoreDelta, reasons, meta) {
+    return {
+      decision: "FLAG" /* FLAG */,
+      allow: true,
+      riskScore: scoreDelta,
+      scoreDelta,
+      reasons,
+      meta
+    };
+  }
+};
+
+// src/engine/intent.router.ts
 var IntentRouter = class {
-  constructor() {
+  constructor(moduleRef) {
+    this.moduleRef = moduleRef;
+    this.logger = new import_common2.Logger(IntentRouter.name);
     /** Internal registry of dynamic intent handlers */
     this.handlers = /* @__PURE__ */ new Map();
+    /** Per-intent sensor classes (resolved at call time) */
+    this.intentSensors = /* @__PURE__ */ new Map();
+    /** Per-intent body decoders */
+    this.intentDecoders = /* @__PURE__ */ new Map();
+    /** Per-intent TLV schemas */
+    this.intentSchemas = /* @__PURE__ */ new Map();
+    /** Per-intent custom validators */
+    this.intentValidators = /* @__PURE__ */ new Map();
+    /** Per-intent operation kind */
+    this.intentKinds = /* @__PURE__ */ new Map();
+  }
+  getSchema(intent) {
+    return this.intentSchemas.get(intent);
+  }
+  getValidators(intent) {
+    return this.intentValidators.get(intent);
+  }
+  has(intent) {
+    return this.handlers.has(intent) || IntentRouter.BUILTIN_INTENTS.has(intent);
+  }
+  getRegisteredIntents() {
+    return [...IntentRouter.BUILTIN_INTENTS, ...this.handlers.keys()];
+  }
+  getIntentEntry(intent) {
+    if (!this.has(intent)) return null;
+    return {
+      schema: this.intentSchemas.get(intent),
+      validators: this.intentValidators.get(intent),
+      hasSensors: this.intentSensors.has(intent),
+      builtin: IntentRouter.BUILTIN_INTENTS.has(intent),
+      kind: this.intentKinds.get(intent)
+    };
   }
   /**
    * Registers a handler for a specific intent.
@@ -491,6 +655,16 @@ var IntentRouter = class {
       } else {
         this.register(intentName, fn);
       }
+      this.registerIntentMeta(intentName, Object.getPrototypeOf(instance), String(route.methodName));
+    }
+    const proto = Object.getPrototypeOf(instance);
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      const meta = Reflect.getMetadata(INTENT_METADATA_KEY, proto, key);
+      if (!meta?.intent) continue;
+      if (!this.handlers.has(meta.intent)) {
+        this.register(meta.intent, instance[key].bind(instance));
+      }
+      this.registerIntentMeta(meta.intent, proto, key);
     }
   }
   /**
@@ -514,6 +688,7 @@ var IntentRouter = class {
       intent = new TextDecoder().decode(intentBytes);
       let effect;
       if (intent === "system.ping" || intent === "public.ping") {
+        this.logger.debug("PING received");
         effect = {
           ok: true,
           effect: "pong",
@@ -554,6 +729,7 @@ var IntentRouter = class {
           if (!innerIntent) {
             throw new Error("INTENT.EXEC missing inner intent");
           }
+          this.logger.debug(`EXEC: routing to inner intent '${innerIntent}'`);
           const innerFrame = {
             ...frame,
             headers: new Map(frame.headers),
@@ -569,8 +745,23 @@ var IntentRouter = class {
         if (!handler) {
           throw new Error(`Intent not found: ${intent}`);
         }
+        const sensorClasses = this.intentSensors.get(intent);
+        if (sensorClasses && sensorClasses.length > 0) {
+          await this.runIntentSensors(sensorClasses, intent, frame);
+        }
+        const decoder = this.intentDecoders.get(intent);
+        let decodedBody = frame.body;
+        if (decoder) {
+          try {
+            decodedBody = decoder(Buffer.from(frame.body));
+          } catch (decodeErr) {
+            throw new Error(
+              `IntentBody decode failed for ${intent}: ${decodeErr.message}`
+            );
+          }
+        }
         if (typeof handler === "function") {
-          const resultBody = await handler(frame.body, frame.headers);
+          const resultBody = decoder ? await handler(decodedBody, frame.headers) : await handler(frame.body, frame.headers);
           effect = {
             ok: true,
             effect: "complete",
@@ -580,10 +771,7 @@ var IntentRouter = class {
           if (typeof handler.handle === "function") {
             effect = await handler.handle(frame);
           } else if (typeof handler.execute === "function") {
-            const bodyRes = await handler.execute(
-              frame.body,
-              frame.headers
-            );
+            const bodyRes = decoder ? await handler.execute(decodedBody, frame.headers) : await handler.execute(frame.body, frame.headers);
             effect = {
               ok: true,
               effect: "complete",
@@ -596,20 +784,130 @@ var IntentRouter = class {
           }
         }
       }
-      this.recordLatency(intent, start);
+      this.logIntent(intent, start, true);
       return effect;
     } catch (e) {
-      console.error(`Error routing intent ${intent}:`, e.message);
+      this.logIntent(intent, start, false, e.message);
       throw e;
     }
   }
-  recordLatency(intent, start) {
+  logIntent(intent, start, ok, error) {
     const diff = process.hrtime(start);
-    void diff;
+    const ms = (diff[0] * 1e3 + diff[1] / 1e6).toFixed(2);
+    if (ok) {
+      this.logger.debug(`${intent} completed in ${ms}ms`);
+    } else {
+      this.logger.warn(`${intent} failed in ${ms}ms - ${error}`);
+    }
+  }
+  registerIntentMeta(intent, proto, methodName) {
+    const decoder = Reflect.getMetadata(INTENT_BODY_KEY, proto, methodName);
+    if (decoder) {
+      this.intentDecoders.set(intent, decoder);
+    }
+    const sensors = Reflect.getMetadata(INTENT_SENSORS_KEY, proto, methodName);
+    if (sensors && Array.isArray(sensors) && sensors.length > 0) {
+      this.intentSensors.set(intent, sensors);
+    }
+    const meta = Reflect.getMetadata(INTENT_METADATA_KEY, proto, methodName);
+    if (meta) {
+      this.storeSchema(meta);
+      if (meta.kind) {
+        this.intentKinds.set(intent, meta.kind);
+      }
+    }
+  }
+  async runIntentSensors(sensorClasses, intent, frame) {
+    if (!this.moduleRef) return;
+    for (const SensorClass of sensorClasses) {
+      let sensor;
+      try {
+        sensor = this.moduleRef.get(SensorClass, { strict: false });
+      } catch {
+        this.logger.warn(
+          `@IntentSensors: could not resolve ${SensorClass.name} for ${intent}`
+        );
+        continue;
+      }
+      const sensorInput = {
+        rawBytes: frame.body,
+        intent,
+        body: frame.body,
+        headerTLVs: frame.headers,
+        metadata: { phase: "intent", intent }
+      };
+      if (sensor.supports && !sensor.supports(sensorInput)) continue;
+      const decision = normalizeSensorDecision(await sensor.run(sensorInput));
+      if (!decision.allow) {
+        const reason = decision.reasons[0] || `${sensor.name}:DENIED`;
+        this.logger.warn(
+          `Intent sensor ${sensor.name} denied ${intent}: ${reason}`
+        );
+        throw new Error(`SENSOR_DENY:${reason}`);
+      }
+    }
+  }
+  storeSchema(meta) {
+    if (meta.dto) {
+      if (meta.tlv && meta.tlv.length > 0) {
+        this.logger.warn(
+          `${meta.intent}: both 'dto' and 'tlv' specified - using dto, ignoring tlv`
+        );
+      }
+      const extracted = extractDtoSchema(meta.dto);
+      const schema2 = {
+        intent: meta.intent,
+        version: 1,
+        bodyProfile: meta.bodyProfile || "TLV_MAP",
+        fields: extracted.fields.map((f) => ({
+          name: f.name,
+          tlv: f.tag,
+          kind: f.kind,
+          required: f.required,
+          maxLen: f.maxLen,
+          max: f.max,
+          scope: f.scope
+        }))
+      };
+      this.intentSchemas.set(meta.intent, schema2);
+      if (extracted.validators.size > 0) {
+        this.intentValidators.set(meta.intent, extracted.validators);
+      }
+      if (!this.intentDecoders.has(meta.intent)) {
+        this.intentDecoders.set(meta.intent, buildDtoDecoder(meta.dto));
+      }
+      return;
+    }
+    if (!meta.tlv || meta.tlv.length === 0) return;
+    const schema = {
+      intent: meta.intent,
+      version: 1,
+      bodyProfile: meta.bodyProfile || "TLV_MAP",
+      fields: meta.tlv.map((f) => ({
+        name: f.name,
+        tlv: f.tag,
+        kind: f.kind,
+        required: f.required,
+        maxLen: f.maxLen,
+        max: f.max,
+        scope: f.scope
+      }))
+    };
+    this.intentSchemas.set(meta.intent, schema);
   }
 };
+/** Intents handled inline in route() — not in `handlers` map */
+IntentRouter.BUILTIN_INTENTS = /* @__PURE__ */ new Set([
+  "system.ping",
+  "public.ping",
+  "system.time",
+  "system.echo",
+  "INTENT.EXEC",
+  "axis.intent.exec"
+]);
 IntentRouter = __decorateClass([
-  (0, import_common2.Injectable)()
+  (0, import_common2.Injectable)(),
+  __decorateParam(0, (0, import_common2.Optional)())
 ], IntentRouter);
 
 // src/core/constants.ts
@@ -1985,105 +2283,6 @@ function buildPacket(hdr, body, sig, flags = 0) {
   };
 }
 
-// src/sensor/axis-sensor.ts
-var Decision = /* @__PURE__ */ ((Decision2) => {
-  Decision2["ALLOW"] = "ALLOW";
-  Decision2["DENY"] = "DENY";
-  Decision2["THROTTLE"] = "THROTTLE";
-  Decision2["FLAG"] = "FLAG";
-  return Decision2;
-})(Decision || {});
-function normalizeSensorDecision(sensorDecision) {
-  if ("action" in sensorDecision) {
-    switch (sensorDecision.action) {
-      case "ALLOW":
-        return {
-          allow: true,
-          riskScore: 0,
-          reasons: [],
-          meta: sensorDecision.meta
-        };
-      case "DENY":
-        return {
-          allow: false,
-          riskScore: 100,
-          reasons: [sensorDecision.code, sensorDecision.reason].filter(
-            Boolean
-          ),
-          meta: sensorDecision.meta,
-          retryAfterMs: sensorDecision.retryAfterMs
-        };
-      case "THROTTLE":
-        return {
-          allow: false,
-          riskScore: 50,
-          reasons: ["RATE_LIMIT"],
-          retryAfterMs: sensorDecision.retryAfterMs,
-          meta: sensorDecision.meta
-        };
-      case "FLAG":
-        return {
-          allow: true,
-          riskScore: sensorDecision.scoreDelta,
-          reasons: sensorDecision.reasons,
-          meta: sensorDecision.meta
-        };
-    }
-  }
-  return {
-    allow: sensorDecision.allow,
-    riskScore: sensorDecision.riskScore,
-    reasons: sensorDecision.reasons,
-    tags: sensorDecision.tags,
-    meta: sensorDecision.meta,
-    tighten: sensorDecision.tighten,
-    retryAfterMs: sensorDecision.retryAfterMs
-  };
-}
-var SensorDecisions = {
-  allow(meta, tags) {
-    return {
-      decision: "ALLOW" /* ALLOW */,
-      allow: true,
-      riskScore: 0,
-      reasons: [],
-      tags,
-      meta
-    };
-  },
-  deny(code, reason, meta) {
-    return {
-      decision: "DENY" /* DENY */,
-      allow: false,
-      riskScore: 100,
-      code,
-      reasons: [code, reason].filter(Boolean),
-      meta
-    };
-  },
-  throttle(retryAfterMs, meta) {
-    return {
-      decision: "THROTTLE" /* THROTTLE */,
-      allow: false,
-      riskScore: 50,
-      retryAfterMs,
-      code: "RATE_LIMIT",
-      reasons: ["RATE_LIMIT"],
-      meta
-    };
-  },
-  flag(scoreDelta, reasons, meta) {
-    return {
-      decision: "FLAG" /* FLAG */,
-      allow: true,
-      riskScore: scoreDelta,
-      scoreDelta,
-      reasons,
-      meta
-    };
-  }
-};
-
 // src/security/scopes.ts
 function hasScope(scopes, required) {
   if (!Array.isArray(scopes) || scopes.length === 0) {
@@ -2381,14 +2580,246 @@ function isTimestampValid(ts, skewSeconds = 120) {
   const diff = Math.abs(now - ts);
   return diff <= skewSeconds;
 }
+
+// src/upload/axis-files.handlers.ts
+var import_common3 = require("@nestjs/common");
+var crypto2 = __toESM(require("crypto"));
+
+// src/upload/upload.tokens.ts
+var AXIS_UPLOAD_SESSION_STORE = "AXIS_UPLOAD_SESSION_STORE";
+var AXIS_UPLOAD_FILE_STORE = "AXIS_UPLOAD_FILE_STORE";
+var AXIS_UPLOAD_RECEIPT_SIGNER = "AXIS_UPLOAD_RECEIPT_SIGNER";
+
+// src/upload/axis-files.handlers.ts
+var AxisFilesDownloadHandler = class {
+  constructor(sessions, files) {
+    this.sessions = sessions;
+    this.files = files;
+    this.logger = new import_common3.Logger(AxisFilesDownloadHandler.name);
+    this.name = "axis.files.download";
+    this.open = true;
+    this.description = "File download handler";
+  }
+  async execute(body, headers) {
+    const h = headers;
+    if (!h) throw new Error("MISSING_HEADERS");
+    const uploadIdBytes = h.get(20);
+    if (!uploadIdBytes) throw new Error("MISSING_UPLOAD_ID");
+    const uploadId = new TextDecoder().decode(uploadIdBytes);
+    let rangeStart = 0;
+    let rangeLen = -1;
+    const startBytes = h.get(21);
+    if (startBytes) {
+      const { value } = (0, import_axis_protocol3.decodeVarint)(startBytes);
+      rangeStart = value;
+    }
+    const lenBytes = h.get(22);
+    if (lenBytes) {
+      const { value } = (0, import_axis_protocol3.decodeVarint)(lenBytes);
+      rangeLen = value;
+    }
+    const session = await this.sessions.findByFileId(uploadId);
+    if (!session) {
+      throw new Error(`SESSION_NOT_FOUND: ${uploadId}`);
+    }
+    if (session.status !== "COMPLETE") {
+      throw new Error(`FILE_NOT_READY: Status is ${session.status}`);
+    }
+    const stat = await this.files.statFinal(
+      uploadId,
+      session.filename
+    );
+    const fileSize = stat.size;
+    if (rangeStart < 0) rangeStart = 0;
+    if (rangeStart >= fileSize) throw new Error("RANGE_OUT_OF_BOUNDS");
+    let end = fileSize;
+    if (rangeLen >= 0) {
+      end = Math.min(rangeStart + rangeLen, fileSize);
+    }
+    const actualLen = end - rangeStart;
+    const buffer = await this.files.readFinalRange(
+      uploadId,
+      session.filename,
+      rangeStart,
+      actualLen
+    );
+    const responseHeaders = /* @__PURE__ */ new Map();
+    responseHeaders.set(30, (0, import_axis_protocol3.encodeVarint)(fileSize));
+    responseHeaders.set(31, (0, import_axis_protocol3.encodeVarint)(rangeStart));
+    responseHeaders.set(32, (0, import_axis_protocol3.encodeVarint)(actualLen));
+    return {
+      ok: true,
+      effect: "FILE_PART",
+      body: buffer,
+      headers: responseHeaders
+    };
+  }
+};
+__decorateClass([
+  Intent("file.download", { absolute: true, kind: "read" })
+], AxisFilesDownloadHandler.prototype, "execute", 1);
+AxisFilesDownloadHandler = __decorateClass([
+  Handler("axis.files.download"),
+  (0, import_common3.Injectable)(),
+  __decorateParam(0, (0, import_common3.Inject)(AXIS_UPLOAD_SESSION_STORE)),
+  __decorateParam(1, (0, import_common3.Inject)(AXIS_UPLOAD_FILE_STORE))
+], AxisFilesDownloadHandler);
+var AxisFilesFinalizeHandler = class {
+  constructor(sessions, files, keyring) {
+    this.sessions = sessions;
+    this.files = files;
+    this.keyring = keyring;
+    this.logger = new import_common3.Logger(AxisFilesFinalizeHandler.name);
+    this.name = "axis.files.finalize";
+    this.open = false;
+    this.description = "File upload finalization handler";
+  }
+  async execute(body, headers) {
+    const bodyStr = new TextDecoder().decode(body);
+    const req = JSON.parse(bodyStr);
+    const { fileId, expectedHash } = req;
+    if (!fileId) throw new Error("MISSING_FILE_ID");
+    const session = await this.sessions.findByFileId(fileId);
+    if (!session) throw new Error("SESSION_NOT_FOUND");
+    if (!await this.files.hasTemp(fileId)) {
+      throw new Error("CHUNKS_NOT_FOUND");
+    }
+    const hash = crypto2.createHash("sha256");
+    const rs = this.files.createTempReadStream(fileId);
+    for await (const chunk of rs) {
+      hash.update(chunk);
+    }
+    const finalHash = hash.digest("hex");
+    if (expectedHash && finalHash !== expectedHash) {
+      throw new Error("HASH_MISMATCH");
+    }
+    const finalPath = await this.files.moveTempToFinal(
+      fileId,
+      session.filename
+    );
+    await this.sessions.updateStatus(fileId, "COMPLETE", null);
+    if (!this.keyring) {
+      this.logger.warn("Receipt signer not configured; returning unsigned receipt");
+      return {
+        ok: true,
+        effect: "FILE_FINALIZED",
+        body: new TextEncoder().encode(
+          JSON.stringify({
+            uploadId: fileId,
+            sha256_final: finalHash,
+            totalSize: session.totalSize,
+            tsMs: Date.now(),
+            path: finalPath
+          })
+        )
+      };
+    }
+    const receiptData = {
+      uploadId: fileId,
+      sha256_final: finalHash,
+      totalSize: session.totalSize,
+      tsMs: Date.now()
+    };
+    const receiptJson = JSON.stringify(receiptData);
+    const receiptBody = new TextEncoder().encode(receiptJson);
+    const SIG_PRESENT = 1;
+    const responseFrame = {
+      flags: SIG_PRESENT,
+      headers: /* @__PURE__ */ new Map(),
+      body: receiptBody,
+      sig: new Uint8Array(0)
+    };
+    const signTarget = getSignTarget(responseFrame);
+    const { sig, kid } = this.keyring.signActive(signTarget);
+    responseFrame.sig = sig;
+    return {
+      ok: true,
+      effect: "FILE_FINALIZED",
+      data: encodeFrame(responseFrame),
+      headers: /* @__PURE__ */ new Map([[1, new TextEncoder().encode(kid)]])
+    };
+  }
+};
+__decorateClass([
+  Intent("file.finalize", { absolute: true, kind: "action" })
+], AxisFilesFinalizeHandler.prototype, "execute", 1);
+AxisFilesFinalizeHandler = __decorateClass([
+  Handler("axis.files.finalize"),
+  (0, import_common3.Injectable)(),
+  __decorateParam(0, (0, import_common3.Inject)(AXIS_UPLOAD_SESSION_STORE)),
+  __decorateParam(1, (0, import_common3.Inject)(AXIS_UPLOAD_FILE_STORE)),
+  __decorateParam(2, (0, import_common3.Optional)()),
+  __decorateParam(2, (0, import_common3.Inject)(AXIS_UPLOAD_RECEIPT_SIGNER))
+], AxisFilesFinalizeHandler);
+
+// src/upload/disk-upload-file.store.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var DiskUploadFileStore = class {
+  constructor(options) {
+    this.uploadDir = options.uploadDir;
+    this.chunkDir = options.chunkDir;
+  }
+  getFinalPath(fileId, filename) {
+    const safeFilename = filename ? path.basename(filename) : fileId;
+    return path.join(this.uploadDir, safeFilename);
+  }
+  getTempPath(fileId) {
+    const safeId = path.basename(fileId);
+    return path.join(this.chunkDir, safeId);
+  }
+  async statFinal(fileId, filename) {
+    const finalPath = this.getFinalPath(fileId, filename);
+    if (!fs.existsSync(finalPath)) {
+      throw new Error("FILE_MISSING_ON_DISK");
+    }
+    const stat = fs.statSync(finalPath);
+    return { path: finalPath, size: stat.size };
+  }
+  async readFinalRange(fileId, filename, start, length) {
+    const finalPath = this.getFinalPath(fileId, filename);
+    const buffer = Buffer.alloc(length);
+    const fd = fs.openSync(finalPath, "r");
+    try {
+      fs.readSync(fd, buffer, 0, length, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return buffer;
+  }
+  async hasTemp(fileId) {
+    const tempPath = this.getTempPath(fileId);
+    return fs.existsSync(tempPath);
+  }
+  async moveTempToFinal(fileId, filename) {
+    const tempPath = this.getTempPath(fileId);
+    const finalPath = this.getFinalPath(fileId, filename);
+    try {
+      await fs.promises.rename(tempPath, finalPath);
+    } catch {
+      await fs.promises.copyFile(tempPath, finalPath);
+      await fs.promises.unlink(tempPath);
+    }
+    return finalPath;
+  }
+  createTempReadStream(fileId) {
+    const tempPath = this.getTempPath(fileId);
+    return fs.createReadStream(tempPath);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ATS1_HDR,
   ATS1_SCHEMA,
   AXIS_MAGIC,
   AXIS_OPCODES,
+  AXIS_UPLOAD_FILE_STORE,
+  AXIS_UPLOAD_RECEIPT_SIGNER,
+  AXIS_UPLOAD_SESSION_STORE,
   AXIS_VERSION,
   Ats1Codec,
+  AxisFilesDownloadHandler,
+  AxisFilesFinalizeHandler,
   AxisFrameZ,
   AxisIdDto,
   AxisPacketTags,
@@ -2401,6 +2832,7 @@ function isTimestampValid(ts, skewSeconds = 120) {
   DEFAULT_CONTRACTS,
   DEFAULT_TIMEOUT,
   Decision,
+  DiskUploadFileStore,
   ERR_BAD_SIGNATURE,
   ERR_CONTRACT_VIOLATION,
   ERR_INVALID_PACKET,
@@ -2412,14 +2844,18 @@ function isTimestampValid(ts, skewSeconds = 120) {
   FLAG_HAS_WITNESS,
   HANDLER_METADATA_KEY,
   Handler,
+  INTENT_BODY_KEY,
   INTENT_METADATA_KEY,
   INTENT_REQUIREMENTS,
   INTENT_ROUTES_KEY,
   INTENT_SENSITIVITY_MAP,
+  INTENT_SENSORS_KEY,
   INTENT_TIMEOUTS,
   Intent,
+  IntentBody,
   IntentRouter,
   IntentSensitivity,
+  IntentSensors,
   MAX_BODY_LEN,
   MAX_FRAME_LEN,
   MAX_HDR_LEN,