Skip to main content

hyprstream_appview/
inventory.rs

1use std::sync::Arc;
2
3#[cfg(feature = "pglite")]
4use std::path::Path;
5
6#[cfg(feature = "pglite")]
7use anyhow::{bail, Context};
8use anyhow::{ensure, Result};
9use async_trait::async_trait;
10use hyprstream_pds_service::federation_intake::{
11    IdentityInventoryReadModel, InventoryEntry, InventoryKind,
12};
13use hyprstream_rpc::auth::mac::SecurityLabel;
14#[cfg(feature = "pglite")]
15use hyprstream_rpc::auth::mac::{Assurance, Level, SecurityContext};
16#[cfg(feature = "pglite")]
17use hyprstream_rpc::identity::UNAUTHENTICATED_DID_SENTINEL;
18#[cfg(feature = "pglite")]
19use pglite::{PGlite, Row};
20
21#[cfg(feature = "pglite")]
22const CREATE_SCHEMA_TEMPLATE: &str = r#"
23CREATE TABLE IF NOT EXISTS appview_inventory (
24    did                 TEXT PRIMARY KEY,
25    handle              TEXT,
26    kind                TEXT NOT NULL,
27    tenant              TEXT,
28    pds_endpoint        TEXT,
29    label_level         SMALLINT NOT NULL,
30    label_assurance     SMALLINT NOT NULL,
31    label_compartments  BIGINT NOT NULL,
32    CHECK (did <> '__UNAUTHENTICATED_DID_SENTINEL__'),
33    CHECK (kind IN ('local', 'federated')),
34    CHECK (
35        (kind = 'local' AND tenant IS NOT NULL AND tenant <> '')
36        OR
37        (kind = 'federated' AND tenant IS NULL)
38    )
39);
40CREATE INDEX IF NOT EXISTS appview_inventory_handle_idx
41    ON appview_inventory (lower(handle));
42"#;
43
44#[cfg(feature = "pglite")]
45const UPSERT: &str = r#"
46INSERT INTO appview_inventory (
47    did, handle, kind, tenant, pds_endpoint,
48    label_level, label_assurance, label_compartments
49)
50VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
51ON CONFLICT (did) DO UPDATE SET
52    handle = EXCLUDED.handle,
53    kind = EXCLUDED.kind,
54    tenant = EXCLUDED.tenant,
55    pds_endpoint = EXCLUDED.pds_endpoint,
56    label_level = EXCLUDED.label_level,
57    label_assurance = EXCLUDED.label_assurance,
58    label_compartments = EXCLUDED.label_compartments
59WHERE appview_inventory.kind = EXCLUDED.kind
60  AND appview_inventory.tenant IS NOT DISTINCT FROM EXCLUDED.tenant
61  AND EXCLUDED.label_level >= appview_inventory.label_level
62  AND EXCLUDED.label_assurance >= appview_inventory.label_assurance
63  AND (
64      appview_inventory.label_compartments & EXCLUDED.label_compartments
65  ) = appview_inventory.label_compartments
66RETURNING did
67"#;
68
69#[cfg(feature = "pglite")]
70const VISIBLE_QUERY: &str = r#"
71SELECT did, handle, kind, tenant, pds_endpoint
72FROM appview_inventory
73WHERE did <> $1
74  AND label_level <= $2
75  AND label_assurance <= $3
76  AND (label_compartments & $4) = label_compartments
77  AND (
78      $5::text IS NULL
79      OR strpos(lower(did), lower($5)) > 0
80      OR strpos(lower(COALESCE(handle, '')), lower($5)) > 0
81      OR strpos(lower(kind), lower($5)) > 0
82      OR strpos(lower(COALESCE(tenant, '')), lower($5)) > 0
83      OR strpos(lower(COALESCE(pds_endpoint, '')), lower($5)) > 0
84  )
85  AND ($6::text IS NULL OR did > $6)
86ORDER BY did
87LIMIT $7
88"#;
89
90#[cfg(feature = "pglite")]
91const VISIBLE_GET: &str = r#"
92SELECT did, handle, kind, tenant, pds_endpoint
93FROM appview_inventory
94WHERE did = $1
95  AND did <> $2
96  AND label_level <= $3
97  AND label_assurance <= $4
98  AND (label_compartments & $5) = label_compartments
99"#;
100
101/// PGlite-backed derived identity inventory.
102///
103/// The schema and queries use PostgreSQL types/operators. A metal deployment
104/// can implement [`IdentityInventoryReadModel`] against its Postgres pool
105/// without changing the projection or HTTP contracts.
106#[cfg(feature = "pglite")]
107#[derive(Clone)]
108pub struct PGliteIdentityInventory {
109    database: Arc<PGlite>,
110}
111
112#[cfg(feature = "pglite")]
113impl PGliteIdentityInventory {
114    /// Open the embedded Postgres data directory and apply the idempotent schema.
115    pub async fn open(data_dir: impl AsRef<Path>) -> Result<Self> {
116        let database = Arc::new(
117            PGlite::open(data_dir)
118                .await
119                .context("opening AppView PGlite database")?,
120        );
121        Self::from_database(database).await
122    }
123
124    /// Apply the inventory schema to an already-open shared PGlite handle.
125    pub async fn from_database(database: Arc<PGlite>) -> Result<Self> {
126        let schema = CREATE_SCHEMA_TEMPLATE.replace(
127            "__UNAUTHENTICATED_DID_SENTINEL__",
128            UNAUTHENTICATED_DID_SENTINEL,
129        );
130        database
131            .exec(&schema)
132            .await
133            .context("creating AppView inventory schema")?;
134        Ok(Self { database })
135    }
136
137    /// Return the shared embedded Postgres handle for sibling repositories.
138    pub fn database(&self) -> Arc<PGlite> {
139        Arc::clone(&self.database)
140    }
141
142    async fn visible_rows(
143        &self,
144        viewer: &SecurityContext,
145        filter: Option<&str>,
146        after: Option<&str>,
147        limit: usize,
148    ) -> Result<Vec<InventoryEntry>> {
149        ensure!(limit > 0, "inventory page limit must be positive");
150        let limit = i64::try_from(limit).context("inventory page limit exceeds BIGINT")?;
151        let clearance = viewer.clearance();
152        let level = level_code(clearance.level);
153        let assurance = assurance_code(clearance.assurance);
154        let compartments = clearance.compartments.0 as i64;
155        let normalized_filter = filter.map(str::trim).filter(|value| !value.is_empty());
156        let rows = self
157            .database
158            .query(
159                VISIBLE_QUERY,
160                &[
161                    &UNAUTHENTICATED_DID_SENTINEL,
162                    &level,
163                    &assurance,
164                    &compartments,
165                    &normalized_filter,
166                    &after,
167                    &limit,
168                ],
169            )
170            .await
171            .context("querying visible AppView inventory")?;
172        rows.iter().map(decode_entry).collect()
173    }
174}
175
176#[cfg(feature = "pglite")]
177#[async_trait]
178impl IdentityInventoryReadModel for PGliteIdentityInventory {
179    async fn upsert_derived(&self, identity: InventoryEntry, label: SecurityLabel) -> Result<()> {
180        identity.validate()?;
181        ensure!(
182            identity.kind() != InventoryKind::Unauthenticated,
183            "the unauthenticated floor is not a listable inventory host"
184        );
185
186        let kind = kind_name(identity.kind());
187        let did = identity.did();
188        let handle = identity.handle();
189        let tenant = identity.tenant();
190        let pds_endpoint = identity.pds_endpoint();
191        let level = level_code(label.level);
192        let assurance = assurance_code(label.assurance);
193        let compartments = label.compartments.0 as i64;
194        let rows = self
195            .database
196            .query(
197                UPSERT,
198                &[
199                    &did,
200                    &handle,
201                    &kind,
202                    &tenant,
203                    &pds_endpoint,
204                    &level,
205                    &assurance,
206                    &compartments,
207                ],
208            )
209            .await
210            .context("upserting derived AppView inventory entry")?;
211        ensure!(
212            rows.len() == 1,
213            "inventory refresh rejected a kind, tenant, or label write-down for {}",
214            identity.did()
215        );
216        Ok(())
217    }
218
219    async fn query_page(
220        &self,
221        viewer: &SecurityContext,
222        filter: Option<&str>,
223        after: Option<&str>,
224        limit: usize,
225    ) -> Result<Vec<InventoryEntry>> {
226        self.visible_rows(viewer, filter, after, limit).await
227    }
228
229    async fn get(
230        &self,
231        viewer: Option<&SecurityContext>,
232        did: &str,
233    ) -> Result<Option<InventoryEntry>> {
234        let Some(viewer) = viewer else {
235            return Ok(None);
236        };
237        if did == UNAUTHENTICATED_DID_SENTINEL {
238            return Ok(None);
239        }
240        let clearance = viewer.clearance();
241        let level = level_code(clearance.level);
242        let assurance = assurance_code(clearance.assurance);
243        let compartments = clearance.compartments.0 as i64;
244        let rows = self
245            .database
246            .query(
247                VISIBLE_GET,
248                &[
249                    &did,
250                    &UNAUTHENTICATED_DID_SENTINEL,
251                    &level,
252                    &assurance,
253                    &compartments,
254                ],
255            )
256            .await
257            .context("fetching visible AppView inventory entry")?;
258        ensure!(
259            rows.len() <= 1,
260            "inventory DID primary key returned duplicates"
261        );
262        rows.first().map(decode_entry).transpose()
263    }
264}
265
266#[cfg(feature = "pglite")]
267fn decode_entry(row: &Row) -> Result<InventoryEntry> {
268    let did: String = row.get(0).context("decoding inventory DID")?;
269    let handle: Option<String> = row.get(1).context("decoding inventory handle")?;
270    let kind: String = row.get(2).context("decoding inventory kind")?;
271    let tenant: Option<String> = row.get(3).context("decoding inventory tenant")?;
272    let pds_endpoint: Option<String> = row.get(4).context("decoding inventory PDS endpoint")?;
273    match kind.as_str() {
274        "local" => InventoryEntry::local(
275            did,
276            handle,
277            tenant.context("stored local inventory entry has no tenant")?,
278            pds_endpoint,
279        ),
280        "federated" => {
281            ensure!(
282                tenant.is_none(),
283                "stored federated inventory entry carries a tenant"
284            );
285            InventoryEntry::indexed_federated(did, handle, pds_endpoint)
286        }
287        _ => bail!("stored inventory entry has invalid kind {kind:?}"),
288    }
289}
290
291#[cfg(feature = "pglite")]
292const fn level_code(level: Level) -> i16 {
293    level as i16
294}
295
296#[cfg(feature = "pglite")]
297const fn assurance_code(assurance: Assurance) -> i16 {
298    assurance as i16
299}
300
301#[cfg(feature = "pglite")]
302const fn kind_name(kind: InventoryKind) -> &'static str {
303    match kind {
304        InventoryKind::Local => "local",
305        InventoryKind::Federated => "federated",
306        InventoryKind::Unauthenticated => "unauthenticated",
307    }
308}
309
310/// One projection emitted by an authority-owned source.
311///
312/// Construction routes through [`InventoryEntry`] invariant checks. The label
313/// is trusted object metadata supplied by the source, not by a client or SQL.
314#[derive(Clone, Debug)]
315pub struct LabeledInventoryEntry {
316    entry: InventoryEntry,
317    label: SecurityLabel,
318}
319
320impl LabeledInventoryEntry {
321    /// Create a projection from the directory/federation authority boundary.
322    pub fn federated(
323        did: impl Into<String>,
324        handle: Option<String>,
325        pds_endpoint: Option<String>,
326        label: SecurityLabel,
327    ) -> Result<Self> {
328        Ok(Self {
329            entry: InventoryEntry::indexed_federated(did, handle, pds_endpoint)?,
330            label,
331        })
332    }
333
334    /// Create a local projection from a hosted-account authority boundary.
335    pub fn local(
336        did: impl Into<String>,
337        handle: Option<String>,
338        tenant: impl Into<String>,
339        pds_endpoint: Option<String>,
340        label: SecurityLabel,
341    ) -> Result<Self> {
342        Ok(Self {
343            entry: InventoryEntry::local(did, handle, tenant, pds_endpoint)?,
344            label,
345        })
346    }
347}
348
349/// Bulk/bootstrap source for directory-derived foreign projections.
350///
351/// Live federation intake writes directly through
352/// [`IdentityInventoryReadModel::upsert_derived`]; this source is the clean seam
353/// for the directory lane's later snapshot/bootstrap adapter.
354#[async_trait]
355pub trait DirectoryInventorySource: Send + Sync {
356    async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>>;
357}
358
359/// Authority-owned source for local hosted-account projections.
360///
361/// Implementations must derive tenant from the hosted-account binding. A
362/// client payload or database column is never an acceptable source.
363#[async_trait]
364pub trait HostedAccountInventorySource: Send + Sync {
365    async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>>;
366}
367
368/// Explicit empty directory adapter used until the directory lane lands.
369#[derive(Clone, Copy, Debug, Default)]
370pub struct StubDirectoryInventorySource;
371
372#[async_trait]
373impl DirectoryInventorySource for StubDirectoryInventorySource {
374    async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>> {
375        Ok(Vec::new())
376    }
377}
378
379/// Explicit empty hosted-account enumeration adapter.
380///
381/// The merged hosted-PDS mint lane has no global, authority-safe listing API,
382/// so the AppView does not infer tenant from its registration response.
383#[derive(Clone, Copy, Debug, Default)]
384pub struct StubHostedAccountInventorySource;
385
386#[async_trait]
387impl HostedAccountInventorySource for StubHostedAccountInventorySource {
388    async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>> {
389        Ok(Vec::new())
390    }
391}
392
393/// Refresh orchestration for separately landing directory/hosted adapters.
394pub struct InventoryIngestor {
395    inventory: Arc<dyn IdentityInventoryReadModel>,
396}
397
398impl InventoryIngestor {
399    pub fn new(inventory: Arc<dyn IdentityInventoryReadModel>) -> Self {
400        Self { inventory }
401    }
402
403    /// Ingest derived snapshots without exposing source totals to query callers.
404    pub async fn refresh(
405        &self,
406        directory: &dyn DirectoryInventorySource,
407        hosted_accounts: &dyn HostedAccountInventorySource,
408    ) -> Result<()> {
409        for projection in directory.entries().await? {
410            ensure!(
411                projection.entry.kind() == InventoryKind::Federated,
412                "directory source emitted a non-federated projection"
413            );
414            self.inventory
415                .upsert_derived(projection.entry, projection.label)
416                .await?;
417        }
418        for projection in hosted_accounts.entries().await? {
419            ensure!(
420                projection.entry.kind() == InventoryKind::Local,
421                "hosted-account source emitted a non-local projection"
422            );
423            self.inventory
424                .upsert_derived(projection.entry, projection.label)
425                .await?;
426        }
427        Ok(())
428    }
429}
430
431#[cfg(test)]
432mod tests {
433    #![allow(clippy::expect_used, clippy::unwrap_used)]
434
435    use super::*;
436    use hyprstream_pds_service::federation_intake::InMemoryIdentityInventory;
437    #[cfg(feature = "pglite")]
438    use hyprstream_rpc::auth::mac::Assurance;
439    use hyprstream_rpc::auth::mac::{CompartmentSet, Level, SecurityContext, VerifiedKeyMaterial};
440
441    fn viewer(
442        level: Level,
443        assurance: VerifiedKeyMaterial,
444        compartments: CompartmentSet,
445    ) -> SecurityContext {
446        SecurityContext::new(level, compartments, assurance)
447    }
448
449    #[cfg(feature = "pglite")]
450    #[tokio::test]
451    async fn pglite_prefilters_before_materialization_and_preserves_contract() {
452        let temp = tempfile::tempdir_in(std::env::current_dir().unwrap()).unwrap();
453        let inventory = PGliteIdentityInventory::open(temp.path()).await.unwrap();
454        let public = InventoryEntry::indexed_federated(
455            "did:web:public.example",
456            Some("alice.example".to_owned()),
457            Some("https://pds.public.example".to_owned()),
458        )
459        .unwrap();
460        let secret = InventoryEntry::indexed_federated(
461            "did:web:secret.example",
462            Some("secret.example".to_owned()),
463            None,
464        )
465        .unwrap();
466        let local = InventoryEntry::local(
467            "did:web:bob.accounts.example",
468            Some("bob".to_owned()),
469            "tenant-authority",
470            Some("https://pds.local.example".to_owned()),
471        )
472        .unwrap();
473        inventory
474            .upsert_derived(public.clone(), SecurityLabel::bottom())
475            .await
476            .unwrap();
477        inventory
478            .upsert_derived(
479                secret.clone(),
480                SecurityLabel::new(
481                    Level::Secret,
482                    Assurance::PqHybrid,
483                    CompartmentSet::single(7),
484                ),
485            )
486            .await
487            .unwrap();
488        inventory
489            .upsert_derived(
490                local.clone(),
491                SecurityLabel::new(
492                    Level::Internal,
493                    Assurance::Classical,
494                    CompartmentSet::single(4),
495                ),
496            )
497            .await
498            .unwrap();
499        let demotion = inventory
500            .upsert_derived(
501                InventoryEntry::indexed_federated(
502                    local.did(),
503                    Some("attacker-refresh.example".to_owned()),
504                    None,
505                )
506                .unwrap(),
507                SecurityLabel::bottom(),
508            )
509            .await
510            .unwrap_err();
511        assert!(demotion.to_string().contains("write-down"));
512        let label_write_down = inventory
513            .upsert_derived(secret.clone(), SecurityLabel::bottom())
514            .await
515            .unwrap_err();
516        assert!(label_write_down.to_string().contains("write-down"));
517
518        let floor = viewer(
519            Level::Public,
520            VerifiedKeyMaterial::Unverified,
521            CompartmentSet::EMPTY,
522        );
523        let floor_visible = inventory.query(&floor, None).await.unwrap();
524        assert_eq!(floor_visible, vec![public.clone()]);
525        assert_eq!(
526            inventory.query(&floor, Some("secret")).await.unwrap(),
527            Vec::<InventoryEntry>::new()
528        );
529        assert_eq!(
530            inventory.query(&floor, Some("ALICE")).await.unwrap(),
531            vec![public.clone()]
532        );
533        assert!(
534            inventory.query(&floor, Some("%")).await.unwrap().is_empty(),
535            "SQL filters must treat wildcard characters as literal substrings"
536        );
537        assert_eq!(
538            inventory.get(Some(&floor), secret.did()).await.unwrap(),
539            None
540        );
541        assert_eq!(
542            inventory
543                .get(Some(&floor), "did:web:missing.example")
544                .await
545                .unwrap(),
546            None
547        );
548
549        let privileged = viewer(
550            Level::Secret,
551            VerifiedKeyMaterial::PqHybrid,
552            CompartmentSet::single(4).union(CompartmentSet::single(7)),
553        );
554        assert_eq!(
555            inventory.query(&privileged, None).await.unwrap(),
556            vec![local.clone(), public.clone(), secret.clone()]
557        );
558        assert_eq!(
559            inventory
560                .query_page(&privileged, None, None, 2)
561                .await
562                .unwrap(),
563            vec![local, public.clone()]
564        );
565        assert_eq!(
566            inventory
567                .query_page(&privileged, None, Some(public.did()), 2)
568                .await
569                .unwrap(),
570            vec![secret]
571        );
572
573        let wire = serde_json::to_value(&floor_visible).unwrap();
574        let row = &wire.as_array().unwrap()[0];
575        assert!(row.get("quicUrl").is_none());
576        assert!(row.get("certHash").is_none());
577        assert!(wire.get("total").is_none());
578        assert!(wire.get("hiddenCount").is_none());
579
580        let rejected = InventoryEntry::indexed_federated(UNAUTHENTICATED_DID_SENTINEL, None, None)
581            .unwrap_err();
582        assert!(rejected.to_string().contains("unauthenticated floor"));
583    }
584
585    #[tokio::test]
586    async fn source_stubs_are_explicitly_empty() {
587        assert!(StubDirectoryInventorySource
588            .entries()
589            .await
590            .unwrap()
591            .is_empty());
592        assert!(StubHostedAccountInventorySource
593            .entries()
594            .await
595            .unwrap()
596            .is_empty());
597    }
598
599    struct StaticDirectory(Vec<LabeledInventoryEntry>);
600
601    #[async_trait]
602    impl DirectoryInventorySource for StaticDirectory {
603        async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>> {
604            Ok(self.0.clone())
605        }
606    }
607
608    struct StaticHostedAccounts(Vec<LabeledInventoryEntry>);
609
610    #[async_trait]
611    impl HostedAccountInventorySource for StaticHostedAccounts {
612        async fn entries(&self) -> Result<Vec<LabeledInventoryEntry>> {
613            Ok(self.0.clone())
614        }
615    }
616
617    #[tokio::test]
618    async fn source_refresh_preserves_local_tenant_authority_boundary() {
619        let inventory = Arc::new(InMemoryIdentityInventory::default());
620        let ingestor = InventoryIngestor::new(inventory.clone());
621        let directory = StaticDirectory(vec![LabeledInventoryEntry::federated(
622            "did:web:foreign.example",
623            Some("foreign.example".to_owned()),
624            Some("https://pds.foreign.example".to_owned()),
625            SecurityLabel::bottom(),
626        )
627        .unwrap()]);
628        let hosted = StaticHostedAccounts(vec![LabeledInventoryEntry::local(
629            "did:web:alice.accounts.example",
630            Some("alice".to_owned()),
631            "tenant-authority",
632            Some("https://pds.local.example".to_owned()),
633            SecurityLabel::bottom(),
634        )
635        .unwrap()]);
636
637        ingestor.refresh(&directory, &hosted).await.unwrap();
638        let visible = inventory
639            .list(&viewer(
640                Level::Public,
641                VerifiedKeyMaterial::Unverified,
642                CompartmentSet::EMPTY,
643            ))
644            .await
645            .unwrap();
646        assert_eq!(visible.len(), 2);
647        let local = visible
648            .iter()
649            .find(|entry| entry.kind() == InventoryKind::Local)
650            .unwrap();
651        assert_eq!(local.tenant(), Some("tenant-authority"));
652        let federated = visible
653            .iter()
654            .find(|entry| entry.kind() == InventoryKind::Federated)
655            .unwrap();
656        assert_eq!(federated.tenant(), None);
657        assert!(
658            InventoryEntry::local("did:web:invalid.example", None, "", None).is_err(),
659            "a local projection without an authority tenant must fail closed"
660        );
661    }
662}