feat(vault): name who declared the content a seal covers (#196)

Author: LKSNDRTMLKV

CHANGELOG.md

@@ -12,6 +12,29 @@ under the pre-1.0 conventions in [VERSIONING.md](docs/governance/VERSIONING.md):
 
 ### Added
 
+- **The seal route names who declared the content it covers.**
+  `GET /api/v1/dpp/{dppId}/seal` gains `declaredBy`, carrying the manufacturer
+  and Annex III(k) operator identifier frozen at publish, a
+  `responsibilityMayHaveTransferred` flag, and a note stating the distinction
+  outright.
+
+  A seal proves a document came from whoever holds the certificate and says
+  nothing about *scope*, so "we vouch for this content" and "we transmitted this
+  intact" look identical. Every audience view strips the seal, which makes this
+  the one surface where the two can be collapsed — and its readers being
+  authenticated and technical is a reason to be more careful, not less.
+
+  **Only a completed handover sets the flag.** An initiated transfer nobody
+  accepted has moved nothing, and reporting it would claim a transfer that may
+  still be rejected. The names cannot simply be updated instead: they are frozen
+  into the sealed bytes and the seal covers them, so a "current operator" field
+  would be an unverifiable claim sitting beside a verifiable document. The flag
+  says the answer is historical and points at where the current one lives.
+
+  A transfer-store failure now fails the read rather than defaulting the flag to
+  `false` — that default is a positive claim that responsibility has not moved,
+  which is worse than serving nothing.
+
 - **The contract gate now checks documented error codes.** It compared schemas,
   numeric bounds, enum variants, query parameters, request bodies and route
   coverage — everything except what a route says goes *wrong*. A status code has

api/components/schemas/SealDeclarer.yaml

@@ -0,0 +1,45 @@
+type: object
+description: |
+  Who declared the content a seal covers, which is not who sealed it.
+
+  A seal proves a document came from whoever holds the certificate. It carries no
+  statement about *scope*: "we vouch for this content" and "we transmitted this
+  intact" look identical. A response that serves a seal and names no declaring
+  party invites the reader to collapse the two, whatever anyone intended.
+
+  Every audience view strips the seal, so this is the only surface where that
+  collapse is reachable — and its readers being authenticated and technical makes
+  them more likely to build on the assumption, not less.
+required:
+  - manufacturer
+  - operatorIdentifier
+  - responsibilityMayHaveTransferred
+  - note
+properties:
+  manufacturer:
+    type: string
+    description: The manufacturer named in the sealed passport, frozen at publish.
+    example: TestCorp GmbH
+  operatorIdentifier:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The Annex III(k) unique operator identifier recorded at publish. `null`
+      means none was recorded — never that none applies.
+  responsibilityMayHaveTransferred:
+    type: boolean
+    description: |
+      True when the passport's transfer chain records a **completed** handover,
+      so the party responsible now is not the one named above. An initiated
+      handover nobody accepted has moved nothing and does not set this.
+
+      The names above are frozen into the sealed bytes and cannot be rewritten —
+      a published passport's content is immutable and the seal covers it — so
+      this flag is the only honest way to say the answer above is historical
+      rather than current.
+  note:
+    type: string
+    description: >-
+      States the sealing/authorship distinction outright rather than leaving it
+      to be inferred from field names, in the same spirit as `verification`.

api/components/schemas/SealResponse.yaml

@@ -3,6 +3,7 @@ description: >-
   The eIDAS seal, plus what is needed to check it — and an explicit statement of
   what this node did **not** check.
 required:
+  - declaredBy
   - format
   - sealValue
   - sealedAt
@@ -12,6 +13,8 @@ required:
   - coverage
   - verification
 properties:
+  declaredBy:
+    $ref: ./SealDeclarer.yaml
   format:
     type: string
     description: AdES format of `sealValue`.

api/openapi.bundled.json

@@ -5627,6 +5627,38 @@
           }
         }
       },
+      "SealDeclarer": {
+        "type": "object",
+        "description": "Who declared the content a seal covers, which is not who sealed it.\n\nA seal proves a document came from whoever holds the certificate. It carries no\nstatement about *scope*: \"we vouch for this content\" and \"we transmitted this\nintact\" look identical. A response that serves a seal and names no declaring\nparty invites the reader to collapse the two, whatever anyone intended.\n\nEvery audience view strips the seal, so this is the only surface where that\ncollapse is reachable — and its readers being authenticated and technical makes\nthem more likely to build on the assumption, not less.\n",
+        "required": [
+          "manufacturer",
+          "operatorIdentifier",
+          "responsibilityMayHaveTransferred",
+          "note"
+        ],
+        "properties": {
+          "manufacturer": {
+            "type": "string",
+            "description": "The manufacturer named in the sealed passport, frozen at publish.",
+            "example": "TestCorp GmbH"
+          },
+          "operatorIdentifier": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The Annex III(k) unique operator identifier recorded at publish. `null` means none was recorded — never that none applies."
+          },
+          "responsibilityMayHaveTransferred": {
+            "type": "boolean",
+            "description": "True when the passport's transfer chain records a **completed** handover,\nso the party responsible now is not the one named above. An initiated\nhandover nobody accepted has moved nothing and does not set this.\n\nThe names above are frozen into the sealed bytes and cannot be rewritten —\na published passport's content is immutable and the seal covers it — so\nthis flag is the only honest way to say the answer above is historical\nrather than current.\n"
+          },
+          "note": {
+            "type": "string",
+            "description": "States the sealing/authorship distinction outright rather than leaving it to be inferred from field names, in the same spirit as `verification`."
+          }
+        }
+      },
       "Coverage": {
         "type": "string",
         "description": "Whether the stored seal covers the passport's current signature. Answered from this node's record of what it *asked* to be sealed — weaker than a validator's verdict, stronger than nothing: it cannot confirm the CAdES, but a passport re-published after sealing is knowable without any AdES tooling.",
@@ -5640,6 +5672,7 @@
         "type": "object",
         "description": "The eIDAS seal, plus what is needed to check it — and an explicit statement of what this node did **not** check.",
         "required": [
+          "declaredBy",
           "format",
           "sealValue",
           "sealedAt",
@@ -5650,6 +5683,9 @@
           "verification"
         ],
         "properties": {
+          "declaredBy": {
+            "$ref": "#/components/schemas/SealDeclarer"
+          },
           "format": {
             "type": "string",
             "description": "AdES format of `sealValue`.",

api/openapi.bundled.yaml

@@ -4258,6 +4258,48 @@ components:
           description: Rows that gave up after exhausting their retries.
         sealingConfigured:
           type: boolean
+    SealDeclarer:
+      type: object
+      description: |
+        Who declared the content a seal covers, which is not who sealed it.
+
+        A seal proves a document came from whoever holds the certificate. It carries no
+        statement about *scope*: "we vouch for this content" and "we transmitted this
+        intact" look identical. A response that serves a seal and names no declaring
+        party invites the reader to collapse the two, whatever anyone intended.
+
+        Every audience view strips the seal, so this is the only surface where that
+        collapse is reachable — and its readers being authenticated and technical makes
+        them more likely to build on the assumption, not less.
+      required:
+        - manufacturer
+        - operatorIdentifier
+        - responsibilityMayHaveTransferred
+        - note
+      properties:
+        manufacturer:
+          type: string
+          description: The manufacturer named in the sealed passport, frozen at publish.
+          example: TestCorp GmbH
+        operatorIdentifier:
+          type:
+            - string
+            - 'null'
+          description: The Annex III(k) unique operator identifier recorded at publish. `null` means none was recorded — never that none applies.
+        responsibilityMayHaveTransferred:
+          type: boolean
+          description: |
+            True when the passport's transfer chain records a **completed** handover,
+            so the party responsible now is not the one named above. An initiated
+            handover nobody accepted has moved nothing and does not set this.
+
+            The names above are frozen into the sealed bytes and cannot be rewritten —
+            a published passport's content is immutable and the seal covers it — so
+            this flag is the only honest way to say the answer above is historical
+            rather than current.
+        note:
+          type: string
+          description: States the sealing/authorship distinction outright rather than leaving it to be inferred from field names, in the same spirit as `verification`.
     Coverage:
       type: string
       description: 'Whether the stored seal covers the passport''s current signature. Answered from this node''s record of what it *asked* to be sealed — weaker than a validator''s verdict, stronger than nothing: it cannot confirm the CAdES, but a passport re-published after sealing is knowable without any AdES tooling.'
@@ -4269,6 +4311,7 @@ components:
       type: object
       description: The eIDAS seal, plus what is needed to check it — and an explicit statement of what this node did **not** check.
       required:
+        - declaredBy
         - format
         - sealValue
         - sealedAt
@@ -4278,6 +4321,8 @@ components:
         - coverage
         - verification
       properties:
+        declaredBy:
+          $ref: '#/components/schemas/SealDeclarer'
         format:
           type: string
           description: AdES format of `sealValue`.

crates/dpp-node/tests/openapi_contract.rs

@@ -396,6 +396,7 @@ fn object_cases() -> Vec<ObjectCase> {
     case!("OperatorScanStats", fixtures::operator_scan_stats());
     case!("DailyScanCount", fixtures::daily_scan_count());
     case!("SealResponse", fixtures::seal_response());
+    case!("SealDeclarer", fixtures::seal_declarer());
     case!("SealSummaryResponse", fixtures::seal_summary_response());
     case!("InstalledPlugin", fixtures::installed_plugin());
     case!("WebhookSubscription", fixtures::webhook_subscription());
@@ -2166,7 +2167,7 @@ mod fixtures {
                 CurrentOperatorView, PassportRegistryView, RegistrationCounts, RegistrationView,
                 RegistryRollupView, TransferCounts, TransferView, VerificationView,
             },
-            seal::{Coverage, SealResponse, SealSummaryResponse},
+            seal::{Coverage, SealDeclarer, SealResponse, SealSummaryResponse},
             suspend::SuspendRequest,
             transfer::TransferInitiateRequest,
             validate::ValidateResponse,
@@ -2933,8 +2934,20 @@ mod fixtures {
         }
     }
 
+    pub fn seal_declarer() -> SealDeclarer {
+        SealDeclarer {
+            manufacturer: "TestCorp GmbH".into(),
+            operator_identifier: Some("LEI:529900T8BM49AURSDO55".into()),
+            responsibility_may_have_transferred: true,
+            // A `&'static str` constant on the type, like `verification` below;
+            // the fixture needs a value of the right shape for the key set.
+            note: "the seal attests to the sender, not the author",
+        }
+    }
+
     pub fn seal_response() -> SealResponse {
         SealResponse {
+            declared_by: seal_declarer(),
             format: "CADES".into(),
             seal_value: "MIIB...".into(),
             sealed_at: ts(),

crates/dpp-vault/src/handlers/seal.rs

@@ -13,6 +13,13 @@
 //! carries everything an external validator needs and states plainly what has
 //! and has not been verified.
 //!
+//! It also names **who declared the content**, which is a different party from
+//! whoever sealed it. A seal says a document came from the certificate holder
+//! and nothing about scope, so serving one with no declarer beside it invites
+//! the reader to conclude the sealer authored what it covers. Since every
+//! audience view strips the seal, this is the only surface where that
+//! conclusion is reachable — see [`SealDeclarer`].
+//!
 //! It does answer one narrower question, because it can: **is this seal stale?**
 //! The envelope carries no preimage, but the outbox row that bought it does, and
 //! those rows are never deleted — so a passport re-published after sealing is
@@ -34,10 +41,50 @@ use crate::{middleware::auth::AuthContext, state::AppState};
 
 use super::error::{internal_error, not_found_error, parse_passport_id};
 
+/// Who declared the content a seal covers, which is not who sealed it.
+///
+/// A seal proves a document came from whoever holds the certificate. It carries
+/// no statement about *scope*: "we vouch for this content" and "we transmitted
+/// this intact" look identical. A response that serves a seal and names no
+/// declaring party invites the reader to collapse the two, whatever anyone
+/// intended.
+///
+/// Every audience view strips the seal, so this is the only surface where that
+/// collapse is reachable — and its readers being authenticated and technical
+/// makes them more likely to build on the assumption, not less.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SealDeclarer {
+    /// The manufacturer named in the sealed passport, frozen at publish.
+    pub manufacturer: String,
+    /// The Annex III(k) unique operator identifier recorded at publish, if one
+    /// was. `null` means none was recorded — never that none applies.
+    pub operator_identifier: Option<String>,
+    /// True when this passport's transfer chain records a completed handover, so
+    /// the party responsible **now** is not the one named above.
+    ///
+    /// The names above are frozen into the sealed bytes and cannot be rewritten:
+    /// a published passport's content is immutable, and the seal covers it. So
+    /// this flag is the only honest way to say that the answer above is a
+    /// historical fact rather than a current one.
+    pub responsibility_may_have_transferred: bool,
+    /// Stated rather than left to inference, in the same spirit as
+    /// [`SealResponse::verification`].
+    pub note: &'static str,
+}
+
+const DECLARER_NOTE: &str = "the seal attests that this document came from the holder of the sealing certificate; it makes \
+     no statement about who authored the content. `manufacturer` is the party that declared it, \
+     frozen at publish. Where `responsibilityMayHaveTransferred` is true, the operator responsible \
+     today is a different question — this node's transfer chain records what it was told, and the \
+     EU registry holds the authoritative record between verified actors.";
+
 /// The seal, plus what is needed to check it and what we did not check.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SealResponse {
+    /// Who declared the content, as distinct from who sealed it.
+    pub declared_by: SealDeclarer,
     /// AdES format of `sealValue` — `CADES` for the eID Easy backend.
     pub format: String,
     /// Base64 detached CAdES (`.p7s`) as returned by the QTSP.
@@ -166,9 +213,35 @@ pub async fn seal_handler(
     };
     let coverage = coverage_of(sealed_payload_hash.as_deref(), &payload_hash);
 
+    // Has responsibility moved since this passport was sealed? Only a *completed*
+    // handover counts: an initiated one that nobody accepted has moved nothing,
+    // and reporting it would claim a transfer that may still be rejected. A node
+    // with no transfer store configured records no handovers, so the honest
+    // answer there is `false` rather than an error.
+    //
+    // A store that *errors*, though, fails the whole read. `false` is not a safe
+    // default here — it is a positive claim that responsibility has not moved,
+    // and serving it beside a seal on the strength of a failed query is the one
+    // outcome worse than serving nothing. So the seal becomes unreadable while
+    // the transfer store is down, deliberately.
+    let responsibility_may_have_transferred = match state.service.transfer_store.as_ref() {
+        Some(store) => match store.get_chain(passport_id).await {
+            Ok(Some(chain)) => chain.transfer_count() > 0,
+            Ok(None) => false,
+            Err(e) => return internal_error(e),
+        },
+        None => false,
+    };
+
     (
         StatusCode::OK,
         Json(SealResponse {
+            declared_by: SealDeclarer {
+                manufacturer: passport.manufacturer.name.clone(),
+                operator_identifier: passport.operator_identifier.clone(),
+                responsibility_may_have_transferred,
+                note: DECLARER_NOTE,
+            },
             format: serde_json::to_value(&seal.format)
                 .ok()
                 .and_then(|v| v.as_str().map(ToOwned::to_owned))

crates/dpp-vault/tests/helpers/mod.rs

@@ -15,7 +15,7 @@ use base64::Engine;
 use dpp_dal::pg::{
     PgApiKeyRepo, PgAuditRepo, PgDal, PgEvidenceDossierRepo, PgOperatorConfigRepo, PgPassportRepo,
     PgRegistryIdentityRepo, PgRegistrySyncRepo, PgRegistryTransferRepo, PgScanTelemetryRepo,
-    PgSealOutboxRepo, PgWebhookRepo,
+    PgSealOutboxRepo, PgTransferRepo, PgWebhookRepo,
 };
 use dpp_domain::{
     DppError, GhostArchive, GhostRegistrySync, PassthroughRegistry,
@@ -291,6 +291,12 @@ async fn start_vault_with_identity(
         // selected wires this, so a harness without it reports the sealing
         // surface as unconfigured and cannot exercise it at all.
         .with_seal_outbox(Arc::new(PgSealOutboxRepo::new(dal.clone())))
+        // Same reasoning again, and it had already cost something: without a
+        // transfer store the seal route's `responsibilityMayHaveTransferred`
+        // took its `None => false` branch, so a test asserting the flag was
+        // `false` passed because nothing *could* be recorded rather than
+        // because nothing was.
+        .with_transfer_store(Arc::new(PgTransferRepo::new(dal.clone())))
         .with_evidence_store(Arc::new(PgEvidenceDossierRepo::new(dal.clone()))),
     );
     let operator_service = Arc::new(OperatorService::new(operator_repo));