Factor Handoff Protocol

1. The Core Idea

The Factor Handoff is a custody transfer, not a backup.

When the SWT3 SDK creates an anchor on your system, it holds the raw data (the "factors") needed to prove that anchor is real. At Clearing Level 2 or 3, the SDK needs to get that data safely into your hands before it wipes its own copy and sends the stripped payload to TeNova.

Once the handoff is complete, your copy is the only copy that exists. TeNova's copy has been destroyed. If you lose your copy, no one can help you re-verify that anchor. That is the trade-off of higher clearing levels, and it is by design.

2. What You Receive

The data included in a handoff depends on your clearing level.

At Clearing Level 2

At Level 2, your factors and hashes still go to TeNova. What gets stripped is contextual metadata. The handoff captures what was removed:

At Clearing Level 3

At Level 3, nearly everything is stripped. The handoff captures all the data you need to independently prove any anchor is real:

3. Integration Guide

The SWT3 SDK supports four methods for receiving your factors. You choose one (or more) when you set up the SDK. The handoff always fires after the anchor is sealed but before the clearing engine wipes the local copy.

3.1 Local File Export (Default)

The simplest option. The SDK writes your factor data to a JSON file on your local system. Works everywhere, including air-gapped environments.

from swt3_ai import Witness

witness = Witness(
    tenant_id="ACME_DEFENSE",
    clearing_level=3,
    factor_handoff="file",
    factor_handoff_path="/secure/vault/factors/"
)

import { Witness } from "@tenova/swt3-ai";

const witness = new Witness({
  tenantId: "ACME_DEFENSE",
  clearingLevel: 3,
  factorHandoff: "file",
  factorHandoffPath: "/secure/vault/factors/"
});

Each anchor gets its own file, named by its fingerprint. Store on an encrypted filesystem with restricted permissions (owner read/write only).

3.2 Webhook (Push to Your Vault)

The SDK sends factor data to an HTTPS endpoint you control. Ideal if you run a centralized secrets manager or compliance vault.

witness = Witness(
    tenant_id="ACME_DEFENSE",
    clearing_level=3,
    factor_handoff="webhook",
    factor_handoff_url="https://vault.acme-defense.com/api/v1/factors",
    factor_handoff_headers={"Authorization": "Bearer <your-vault-token>"}
)

const witness = new Witness({
  tenantId: "ACME_DEFENSE",
  clearingLevel: 3,
  factorHandoff: "webhook",
  factorHandoffUrl: "https://vault.acme-defense.com/api/v1/factors",
  factorHandoffHeaders: { Authorization: "Bearer <your-vault-token>" }
});

Safety rules:

• The SDK rejects plaintext HTTP. Your endpoint must use HTTPS (TLS 1.2+).
• Your endpoint must respond with a success code within 5 seconds.
• If unreachable, the SDK retries once after 2 seconds. If that fails, the record goes to a local recovery queue and clearing does NOT proceed.

3.3 HashiCorp Vault

For organizations already using HashiCorp Vault, the SDK writes factors directly to a KV v2 secrets engine.

witness = Witness(
    tenant_id="ACME_DEFENSE",
    clearing_level=3,
    factor_handoff="vault",
    factor_handoff_vault_addr="https://vault.acme-defense.com",
    factor_handoff_vault_token="hvs.your-token",
    factor_handoff_vault_path="secret/data/swt3/factors"
)

const witness = new Witness({
  tenantId: "ACME_DEFENSE",
  clearingLevel: 3,
  factorHandoff: "vault",
  factorHandoffVaultAddr: "https://vault.acme-defense.com",
  factorHandoffVaultToken: "hvs.your-token",
  factorHandoffVaultPath: "secret/data/swt3/factors"
});

We recommend a dedicated Vault policy scoped to the SWT3 factor path so the SDK token can only write to that location.

3.4 Cloud KMS Envelope (AWS, Azure, GCP)

For organizations using cloud key management, the SDK encrypts factor data with a key you control before writing it locally. The encrypted file can be stored anywhere because the data is unreadable without your KMS key.

witness = Witness(
    tenant_id="ACME_DEFENSE",
    clearing_level=3,
    factor_handoff="kms",
    factor_handoff_kms_key_id="arn:aws:kms:us-east-1:123456789:key/abc-def",
    factor_handoff_path="/secure/factors/"
)

const witness = new Witness({
  tenantId: "ACME_DEFENSE",
  clearingLevel: 3,
  factorHandoff: "kms",
  factorHandoffKmsKeyId: "arn:aws:kms:us-east-1:123456789:key/abc-def",
  factorHandoffPath: "/secure/factors/"
});

One encrypted file per anchor. Decryption requires access to the KMS key. Key rotation is managed by your cloud provider.

4. The Safety Guarantee

The handoff follows a strict sequence designed to prevent data loss:

Steps 4 and 5 are the key. If the handoff fails for any reason (your vault is down, the disk is full, the network is unreachable), the SDK stops. It does not clear. It does not transmit. Your factors stay on your system until the handoff succeeds.

5. Independent Verification

Once you hold the factors, you can verify any anchor at any time without contacting TeNova and without any network connection. The formula is:

fingerprint = SHA256("WITNESS:" + tenant_id + ":" + procedure_id + ":" + factor_a + ":" + factor_b + ":" + factor_c + ":" + timestamp_ms)
take the first 12 characters of the hex result

If the fingerprint you compute matches the one in the SWT3 Anchor string, the anchor is valid and has not been tampered with.

import hashlib

def verify(tenant_id, procedure_id, fa, fb, fc, ts_ms, expected):
    msg = f"WITNESS:{tenant_id}:{procedure_id}:{fa}:{fb}:{fc}:{ts_ms}"
    return hashlib.sha256(msg.encode()).hexdigest()[:12] == expected

import { createHash } from "crypto";

function verify(
  tenantId: string, procId: string,
  fa: number, fb: number, fc: number,
  tsMs: number, expected: string
): boolean {
  const msg = `WITNESS:${tenantId}:${procId}:${fa}:${fb}:${fc}:${tsMs}`;
  return createHash("sha256").update(msg).digest("hex").slice(0, 12) === expected;
}

This is the same algorithm used by the TeNova platform, the public verifier at sovereign.tenova.io/verify, and the libswt3 reference implementation. There is no proprietary step, no secret key, and no TeNova dependency.

6. Taking Care of Your Factors

TeNova does not tell you how to store your factors. That is your decision based on your security requirements and regulatory environment. But we strongly recommend:

• Treat factors like credentials. At Clearing Level 3, if you lose them, no one can help you re-verify those anchors. Not TeNova. Not anyone.
• Encrypt them at rest. Whether you use local files, a vault, or cloud storage, factors should always be encrypted.
• Test your recovery process. Pick a random anchor from your ledger, pull the factors from your backup, and run the verification formula. If the result matches, your backup is healthy. Do this periodically.
• Store factors separately from the monitored system. If your application server is compromised, your factor backup should not be on the same machine.
• Retention period. Keep factors for at least as long as your applicable data retention requirements. Three years is common in federal environments. Seven years is typical in financial services. Some healthcare and legal contexts require indefinite retention. Check with your compliance team.

7. Frequently Asked Questions

What happens if I start at Level 1 and later move to Level 3?

The change applies to new anchors only. Anchors created at Level 1 keep whatever data was transmitted at Level 1. You cannot retroactively apply a higher clearing level to existing anchors. You can request deletion of stored metadata for prior anchors through a data removal request (see our Privacy Policy).

Can TeNova see my factors at Level 3?

TeNova receives three numbers and a 12-character fingerprint. We cannot determine what system, model, or inference those numbers relate to because all the context that would make them meaningful was cleared before transmission.

What if my webhook is down during a handoff?

The SDK retries once after a 2-second wait. If that fails, the record goes to a local recovery queue and clearing does not proceed. Your factors are safe. When your webhook recovers, replay the queue to finish the handoff.

Can I use more than one handoff method at the same time?

Yes. You can configure a local file export and a webhook, for example. Both run before clearing proceeds. This gives you redundancy.

Is the handoff payload signed?

The payload includes the SWT3 anchor fingerprint, which is a SHA-256 digest of the factors. If someone tampers with the factors during the handoff, the fingerprint will not match when you try to re-verify. That gives you tamper detection without needing a separate signing step.

What if I need to correct an anchor?

Anchors cannot be edited or deleted. If you discover a verdict was wrong, you create a revocation record that references the original anchor. The original stays in the chain for integrity, but it is marked as revoked with a reason and timestamp. See the Clearing Protocol Addendum, Section F.

8. Implementation Status

Local File Export is available now in both SDKs. Configure factorHandoff: "file" and factorHandoffPath on the Witness constructor. The webhook, Vault, and KMS methods are specified and planned for future releases.