evidence

client.evidence exports an evidence pack over a period and scope. It also makes the refs a customer compares against a pack. To verify a pack offline without enrollment, use verifyPack on Seald Healthcare, not evidence.

export

export exports an evidence pack for a person entitled to Export. For a subject scope, the SDK tokenizes the customer’s identifier for each epoch the period spans. The Seald Healthcare Cloud never sees the identifier.

export(scope: ExportScope, period: { from: Date; to: Date }): Promise<Decided<ExportedPack>>;

func export(_ scope: ExportScope, from: Date, to: Date) async throws -> Decided<ExportedPack>

suspend fun export(scope: ExportScope, from: Instant, to: Instant): Decided<ExportedPack>

Parameter	Type	Description
`scope`	`ExportScope`	The whole tenant, a set of datasets, or one subject.
`period`	`{ from, to }`	The period the pack covers.

Returns: A Decided<ExportedPack>.

Records: Export. See Audit actions.

Who may call it: A person entitled to the Export action.

Errors: no-session, unreachable.

subjectRef

subjectRef makes a ref for a candidate identifier. The customer compares it with the ref in the pack, on its own side. The two refs are equal only for the same subject.

subjectRef(identifier: string, epoch: number): Promise<Ref>;

func subjectRef(_ identifier: String, epoch: Int) async throws -> Ref

suspend fun subjectRef(identifier: String, epoch: Int): Ref

Parameter	Type	Description
`identifier`	string	The customer’s own identifier for the subject, such as a medical record number. The SDK never sends it to the Seald Healthcare Cloud.
`epoch`	number	The epoch the pack’s event falls in.

Returns: A Ref for the identifier at that epoch, to compare with the one in the pack.

Records: Nothing. Not a decision.

Errors: no-session.

personRef

personRef makes a ref for a candidate person, to compare with a ref in the pack.

personRef(person: Person, epoch: number): Promise<Ref>;

func personRef(_ person: Person, epoch: Int) async throws -> Ref

suspend fun personRef(person: Person, epoch: Int): Ref

Parameter	Type	Description
`person`	`Person`	The candidate to resolve.
`epoch`	number	The epoch the pack’s event falls in.

Returns: A Ref for the person at that epoch, to compare with the actor or subject ref in the pack.

Records: Nothing. Not a decision.

Errors: no-session.

epochs

epochs lists the epochs a period spans.

epochs(period: { from: Date; to: Date }): Promise<number[]>;

func epochs(from: Date, to: Date) async throws -> [Int]

suspend fun epochs(from: Instant, to: Instant): List<Int>

Parameter	Type	Description
`period`	`{ from, to }`	The period to list epochs for.

Returns: Every epoch the period spans, to resolve a ref against each.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

Types

ExportScope

type ExportScope = { tenant: true } | { datasets: string[] } | { subject: string };

enum ExportScope {
  case tenant
  case datasets([String])
  case subject(String)
}

sealed interface ExportScope {
  object Tenant : ExportScope
  data class Datasets(val datasets: List<String>) : ExportScope
  data class Subject(val subject: String) : ExportScope
}

Case	Payload	Description
`tenant`	none	Every event in the tenant.
`datasets`	`datasets`	Every event on the named datasets.
`subject`	`subject`	Every event naming this subject: an accounting of disclosures. The SDK tokenizes the identifier on the device per epoch. The Seald Healthcare Cloud never sees the identifier.

ExportedPack

interface ExportedPack {
  packId: string;
  eventId: EventId;
  events: number;
  bytes(): Promise<Bytes>;
}

struct ExportedPack {
  let packId: String
  let eventId: EventId
  let events: Int
  func bytes() async throws -> Data
}

class ExportedPack(
  val packId: String,
  val eventId: EventId,
  val events: Int,
) {
  suspend fun bytes(): ByteArray
}

Field	Type	Description
`packId`	string	Identifies the pack.
`eventId`	`EventId`	The access event of this export.
`events`	number	How many events the pack holds.
`bytes()`	function	The archive, in the evidence pack format. The SDK has sent the exporter’s manifest over it.

Ref

A keyed one-way ref and the epoch of the key that made it.

interface Ref {
  ref: string;
  epoch: number;
}

struct Ref {
  let ref: String
  let epoch: Int
}

data class Ref(
  val ref: String,
  val epoch: Int,
)

Field	Type	Description
`ref`	string	The one-way ref.
`epoch`	number	The epoch of the key that made it.

PackEvent

interface PackEvent {
  id: EventId;
  at: Date;
  actor: Ref;
  organization: string;
  device: RecipientId;
  action: string;
  locator?: Locator;
  version?: number;
  subject?: Ref;
  classification?: Classification;
  policyVersion: string;
  outcome: Outcome;
  reason?: DenyReason;
  riskScore: number;
  offline: boolean;
  hash: string;
}

struct PackEvent {
  let id: EventId
  let at: Date
  let actor: Ref
  let organization: String
  let device: RecipientId
  let action: String
  let locator: Locator?
  let version: Int?
  let subject: Ref?
  let classification: Classification?
  let policyVersion: String
  let outcome: Outcome
  let reason: DenyReason?
  let riskScore: Double
  let offline: Bool
  let hash: String
}

data class PackEvent(
  val id: EventId,
  val at: Instant,
  val actor: Ref,
  val organization: String,
  val device: RecipientId,
  val action: String,
  val locator: Locator?,
  val version: Int?,
  val subject: Ref?,
  val classification: Classification?,
  val policyVersion: String,
  val outcome: Outcome,
  val reason: DenyReason?,
  val riskScore: Double,
  val offline: Boolean,
  val hash: String,
)

Field	Type	Description
`id`	`EventId`	Identifies the event.
`at`	date	When it happened.
`actor`	`Ref`	The device’s person, as a ref.
`organization`	string	The actor’s organization.
`device`	`RecipientId`	The device that made the call.
`action`	string	The action recorded, from Audit actions.
`locator`	`Locator`, optional	The object or key domain, where the event names one.
`version`	number, optional	The version, where the event names one.
`subject`	`Ref`, optional	The record’s subject, as a ref, where the event names one.
`classification`	`Classification`, optional	The object’s classification, where the event names one.
`policyVersion`	string	The policy version in effect when the decision was made.
`outcome`	`Outcome`	`"allow"`, `"deny"` or `"challenge"`.
`reason`	`DenyReason`, optional	Present on a `deny` outcome.
`riskScore`	number	The risk score the decision carried.
`offline`	boolean	Whether the decision was made under an offline lease.
`hash`	string	The event’s own hash, chained for verification.

PackVerification

interface PackVerification {
  verified: boolean;
  failure?: {
    check: 'chain' | 'checkpoint' | 'identity-authority' | 'card' | 'manifest' | 'pack-manifest' | 'policy-version';
    detail: string;
  };
  tenantId: TenantId;
  period: { from: Date; to: Date };
  scope: 'tenant' | 'datasets' | 'subject';
  events: PackEvent[];
  policyVersions: PolicyVersion[];
  checkpoints: { at: Date; authority: string; eventId: EventId }[];
  controlStatus: { [control: string]: unknown };
}

struct PackVerification {
  let verified: Bool
  let failure: Failure?
  let tenantId: TenantId
  let period: (from: Date, to: Date)
  let scope: Scope
  let events: [PackEvent]
  let policyVersions: [PolicyVersion]
  let checkpoints: [(at: Date, authority: String, eventId: EventId)]
  let controlStatus: [String: Any]

  struct Failure { let check: Check; let detail: String }
  enum Check { case chain, checkpoint, identityAuthority, card, manifest, packManifest, policyVersion }
  enum Scope { case tenant, datasets, subject }
}

data class PackVerification(
  val verified: Boolean,
  val failure: Failure?,
  val tenantId: TenantId,
  val period: Period,
  val scope: Scope,
  val events: List<PackEvent>,
  val policyVersions: List<PolicyVersion>,
  val checkpoints: List<Checkpoint>,
  val controlStatus: Map<String, Any>,
) {
  data class Failure(val check: Check, val detail: String)
  enum class Check { CHAIN, CHECKPOINT, IDENTITY_AUTHORITY, CARD, MANIFEST, PACK_MANIFEST, POLICY_VERSION }
  enum class Scope { TENANT, DATASETS, SUBJECT }
  data class Period(val from: Instant, val to: Instant)
  data class Checkpoint(val at: Instant, val authority: String, val eventId: EventId)
}

Field	Type	Description
`verified`	boolean	Whether every check passed.
`failure`	`{ check, detail }`, optional	The first failure, in the order the checks run.
`tenantId`	`TenantId`	The pack’s tenant.
`period`	`{ from, to }`	The period the pack covers.
`scope`	`"tenant"`, `"datasets"` or `"subject"`	The pack’s scope.
`events`	`PackEvent[]`	Every event in the pack.
`policyVersions`	`PolicyVersion[]`	The policy versions in effect over the period.
`checkpoints`	list of at, authority and event id	Each timestamp authority checkpoint over the chain.
`controlStatus`	map of control to status	The control status for the period.

verifyPack produces a PackVerification offline, with no enrollment and no key. It is on Seald Healthcare.