Skip to main content

DOMAIN_MODEL — lock-integration-service

Bundle: SERVICE_OVERVIEW · APPLICATION_LOGIC · API_CONTRACTS · EVENT_SCHEMAS · DATA_MODEL

Source of truth for the port shape: docs/09 §4 LockPort interface. This document specializes the canonical port into the full per-vendor adapter signatures and the aggregate model.

The domain layer is pure TypeScript. It does not import NestJS, Drizzle, Pub/Sub, fetch, or any vendor SDK. All I/O is behind ports defined in application/ports/ (see APPLICATION_LOGIC).

1. Aggregates and entities​

1.1 KeyCredential — root aggregate​

The KeyCredential is the single source of truth for one logical credential's lifetime: who holds it, what rooms it opens, when it is valid, what state it is in, which vendor minted it, and what its replacement lineage is.

import type {
  TenantId, PropertyId, ReservationId, RoomId, GuestId, UserId, ISODate, Brand,
} from '@ghasi/shared/types';

export type KeyCredentialId = Brand<string, 'KeyCredentialId'>;
export type LockDeviceId    = Brand<string, 'LockDeviceId'>;
export type VendorAdapterId = Brand<string, 'VendorAdapterId'>;
export type EncoderSessionId = Brand<string, 'EncoderSessionId'>;
export type MasterKeyId     = Brand<string, 'MasterKeyId'>;
export type OfflineIssuanceId = Brand<string, 'OfflineIssuanceId'>;

export type KeyCredentialKind =
  | 'mobile_app' | 'pin_code' | 'rfid_card' | 'qr_code' | 'nfc_tag';

export type KeyCredentialState =
  | 'requested' | 'pending' | 'active' | 'suspended' | 'revoked' | 'failed';

export type KeyHolderKind = 'guest' | 'staff_master';

export type SuspendReason  = 'no_show' | 'fraud_review' | 'overdue_payment' | 'manual';
export type RevokeReason   = 'checkout' | 'cancellation' | 'security' | 'lost' | 'replaced';
export type FailureReason  = 'vendor_unreachable' | 'vendor_refused' | 'pin_collision_exhausted'
                           | 'no_capable_device' | 'kind_unsupported' | 'cancelled_mid_flight';

export type VendorCode = 'ttlock' | 'salto' | 'assa-abloy' | 'generic-wiegand';

export interface KeyCredentialScope {
  floors?: string[];
  areas?:  ('lobby' | 'gym' | 'pool' | 'spa' | 'parking' | 'back_of_house')[];
}

export interface KeyCredential {
  readonly id:             KeyCredentialId;
  readonly tenantId:       TenantId;
  readonly propertyId:     PropertyId;
  readonly holderKind:     KeyHolderKind;
  readonly reservationId?: ReservationId;          // present when holderKind = 'guest'
  readonly guestId?:       GuestId;
  readonly staffUserId?:   UserId;                 // present when holderKind = 'staff_master'
  readonly kind:           KeyCredentialKind;
  readonly rooms:          RoomId[];               // empty for masters with `areas`-only scope
  readonly scope:          KeyCredentialScope;
  readonly validFrom:      ISODate;
  readonly validUntil:     ISODate;
  readonly state:          KeyCredentialState;
  readonly vendor:         VendorCode;
  readonly vendorAdapterId: VendorAdapterId;
  readonly vendorRef:      string;                 // opaque; never serialized off-aggregate
  readonly provisional:    boolean;                // true only when minted on Electron offline
  readonly idempotencyKey: string;
  readonly issuedAt?:      ISODate;
  readonly suspendedAt?:   ISODate;
  readonly revokedAt?:     ISODate;
  readonly failureReason?: FailureReason;
  readonly suspendReason?: SuspendReason;
  readonly revokeReason?:  RevokeReason;
  readonly replacesId?:    KeyCredentialId;        // lineage on replacement
  readonly replacedById?:  KeyCredentialId;
  readonly version:        number;                 // optimistic concurrency
  readonly createdAt:      ISODate;
  readonly updatedAt:      ISODate;
}

1.2 KeyCredential invariants​

  • I-1. validFrom < validUntil.
  • I-2. holderKind === 'guest' ⇒ reservationId !== undefined && guestId !== undefined && staffUserId === undefined.
  • I-3. holderKind === 'staff_master' ⇒ staffUserId !== undefined && reservationId === undefined.
  • I-4. state === 'revoked' is terminal: no transition out of revoked. Re-issue creates a new id with replacesId set.
  • I-5. state === 'failed' is terminal: no transition out of failed. A retry creates a new credential.
  • I-6. kind === 'rfid_card' ⇒ vendor describeAdapter().capabilities.cardEncoding === true.
  • I-7. provisional === true ⇒ minted by the Electron offline adapter; validUntil <= validFrom + 48h; reconciler must materialize or revoke on next sync.
  • I-8. vendorRef is never present in any DTO returned to consumers, never logged, never replicated to desktop SQLite.
  • I-9. No two state === 'active' credentials may overlap on (tenantId, propertyId, roomId, [validFrom, validUntil]) — enforced by Postgres advisory lock during issue and a partial unique index on the key_credential_rooms join table (see DATA_MODEL §4).
  • I-10. Only KeyCredential aggregate methods may transition state; transitions emit domain events to the aggregate's pending event list and are flushed by the application layer through the outbox.
  • I-11. Cross-tenant references are forbidden — every RoomId, ReservationId, GuestId, UserId is checked against the same tenantId at construction; violation throws CrossTenantReferenceError (MELMASTOON.GENERAL.CROSS_TENANT_REFERENCE, 422).
  • I-12. rooms.length > 0 for guest credentials. Master credentials may have empty rooms if scope.areas covers only common areas.

1.3 KeyCredential state machine​

The full diagram lives in docs/09 §6.1. The aggregate exposes one method per legal transition; each method takes the inputs it needs plus an idempotencyKey and the actor (saga step or operator):

export class KeyCredentialAggregate {
  static request(input: IssueIntent): KeyCredentialAggregate;       // → requested
  markPending(vendorAck: { vendorRef: string }): void;              // requested → pending
  markActive(issuedAt: ISODate): void;                              // pending   → active
  markFailed(reason: FailureReason, vendorMessage?: string): void;  // requested|pending → failed
  suspend(reason: SuspendReason, idempotencyKey: string): void;     // active    → suspended
  unsuspend(idempotencyKey: string): void;                          // suspended → active
  revoke(reason: RevokeReason, idempotencyKey: string): void;       // active|suspended|pending → revoked
  update(input: UpdateInput): void;                                 // active|suspended (validUntil/rooms/scope)
  linkReplacement(newId: KeyCredentialId): void;                    // sets replacedById; only when state === 'revoked' and reason === 'lost' or 'replaced'
  pendingEvents(): readonly DomainEvent[];
  clearPendingEvents(): void;
}

1.4 KeyCredentialAttempt — door-access event (immutable, append-only)​

Door attempts ingested from vendor webhooks. Append-only; never mutated; part of the audit substrate.

export type KeyCredentialAttemptId = Brand<string, 'KeyCredentialAttemptId'>;
export type AttemptOutcome = 'granted' | 'denied';
export type AttemptDenyReason =
  | 'expired' | 'suspended' | 'revoked' | 'wrong_room'
  | 'outside_window' | 'unknown_credential' | 'lock_offline' | 'other';

export interface KeyCredentialAttempt {
  readonly id:               KeyCredentialAttemptId;
  readonly tenantId:         TenantId;
  readonly propertyId:       PropertyId;
  readonly keyCredentialId?: KeyCredentialId;        // null when 'unknown_credential'
  readonly deviceId:         LockDeviceId;
  readonly attemptedAt:      ISODate;                // vendor-reported time
  readonly ingestedAt:       ISODate;                // server time
  readonly outcome:          AttemptOutcome;
  readonly denyReason?:      AttemptDenyReason;
  readonly vendor:           VendorCode;
  readonly vendorEventId:    string;                 // for dedupe; opaque
  readonly metadata:         Record<string, string>; // small, vendor-normalized; never PII
}

1.5 KeyCredentialAttempt invariants​

  • A-1. Append-only — no update method exists; rows are inserted via KeyCredentialAttemptRepository.append().
  • A-2. (vendor, vendorEventId) is unique within a tenant for idempotent ingestion.
  • A-3. attemptedAt <= ingestedAt + clockSkewToleranceMs (5 min) — vendor times in the future are clamped and logged as a warning.
  • A-4. When keyCredentialId references a known credential, the credential's tenantId/propertyId must match the attempt's; mismatch throws CrossTenantReferenceError.

2. LockDevice aggregate​

export interface LockCapabilities {
  readonly mobileKey:        boolean;
  readonly cardEncoding:     boolean;
  readonly pin:              boolean;
  readonly qr:               boolean;
  readonly nfc:              boolean;
  readonly remoteRevoke:     boolean;
  readonly remoteIssue:      boolean;
  readonly offlineIssuance:  boolean;
  readonly scopeFloors:      boolean;
  readonly scopeAreas:       boolean;
}

export interface LockDevice {
  readonly id:           LockDeviceId;
  readonly tenantId:     TenantId;
  readonly propertyId:   PropertyId;
  readonly vendor:       VendorCode;
  readonly vendorDeviceRef: string;                      // opaque vendor identifier
  readonly label:        string;                         // "Room 204 main door"
  readonly rooms:        RoomId[];                       // mapped rooms (often 1)
  readonly capabilities: LockCapabilities;
  readonly online:       boolean;
  readonly battery?:     { percent: number; lowThresholdPercent: number };
  readonly firmware?:    string;
  readonly clockSkewMs?: number;
  readonly lastSeenAt:   ISODate;
  readonly registeredAt: ISODate;
  readonly decommissionedAt?: ISODate;
}

2.1 LockDevice invariants​

  • D-1. vendorDeviceRef is unique within (tenantId, propertyId, vendor).
  • D-2. decommissionedAt !== undefined ⇒ device cannot be returned by listDevices() and any subsequent healthCheck returns online: false.
  • D-3. rooms references RoomIds in the same tenantId/propertyId (cross-tenant reference forbidden).
  • D-4. battery.percent ∈ [0, 100]; lowThresholdPercent ∈ [5, 50]. Crossing the threshold downward emits lock.device.battery_low.v1.

3. VendorAdapter and VendorCredential​

export type AdapterEnvironment = 'sandbox' | 'production';

export type CircuitState = 'closed' | 'open' | 'half_open';

export interface AdapterHealthSnapshot {
  readonly windowSize:        number;
  readonly errorRatePct:      number;
  readonly p95LatencyMs:      number;
  readonly p99LatencyMs:      number;
  readonly circuit:           CircuitState;
  readonly lastTrippedAt?:    ISODate;
  readonly lastError?:        { code: string; vendorMessage?: string; at: ISODate };
}

export interface VendorAdapter {
  readonly id:           VendorAdapterId;
  readonly tenantId:     TenantId;
  readonly propertyId:   PropertyId;
  readonly vendor:       VendorCode;
  readonly environment:  AdapterEnvironment;
  readonly capabilities: LockCapabilities;
  readonly health:       AdapterHealthSnapshot;
  readonly enabled:      boolean;
  readonly precedence:   number;                  // lower = preferred when multiple adapters present
  readonly createdAt:    ISODate;
  readonly updatedAt:    ISODate;
}

export interface VendorCredential {
  readonly id:                 Brand<string, 'VendorCredentialId'>;
  readonly tenantId:           TenantId;
  readonly propertyId:         PropertyId;
  readonly vendor:             VendorCode;
  readonly environment:        AdapterEnvironment;
  readonly secretResourceName: string;            // "projects/<p>/secrets/<n>/versions/latest"
  readonly rotatesAt:          ISODate;           // next scheduled rotation
  readonly fingerprint:        string;            // sha256 of secret bytes for change detection
  readonly createdAt:          ISODate;
  readonly updatedAt:          ISODate;
}

3.1 Invariants​

  • V-1. (tenantId, propertyId, vendor, environment) is unique on VendorAdapter.
  • V-2. VendorCredential.secretResourceName is a Secret Manager resource path; the value bytes are never persisted in Postgres or any other store.
  • V-3. circuit === 'open' ⇒ adapter dispatch returns MELMASTOON.LOCK.VENDOR_UNREACHABLE immediately without an outbound call until half-open.

4. MasterKey and KeyKindPolicy​

export type MasterScope =
  | { kind: 'room';            roomId: RoomId }
  | { kind: 'floor';           floor:  string }
  | { kind: 'rooms_assigned' }                        // computed from open tasks
  | { kind: 'rooms_all' }
  | { kind: 'areas';           areas:  KeyCredentialScope['areas'] }
  | { kind: 'areas_all' }
  | { kind: 'back_of_house' };

export interface MasterKey {
  readonly id:              MasterKeyId;
  readonly keyCredentialId: KeyCredentialId;        // 1:1 with the underlying KeyCredential
  readonly tenantId:        TenantId;
  readonly propertyId:      PropertyId;
  readonly staffUserId:     UserId;
  readonly shiftId?:        Brand<string, 'ShiftId'>;
  readonly scope:           MasterScope;
  readonly validFrom:       ISODate;
  readonly validUntil:      ISODate;
  readonly issuedAt:        ISODate;
  readonly revokedAt?:      ISODate;
}

export interface KeyKindPolicy {
  readonly id:              Brand<string, 'KeyKindPolicyId'>;
  readonly tenantId:        TenantId;
  readonly propertyId:      PropertyId;
  readonly preferredOrder:  KeyCredentialKind[];                 // e.g. ['mobile_app','pin_code','rfid_card']
  readonly fallbackChain:   KeyCredentialKind[];                 // applied on failure of preferred
  readonly maxValidUntilExtensionHours: number;                  // tenant cap
  readonly idVerifyRequiredFor: KeyCredentialKind[];             // require ID-doc snapshot before issue
  readonly noShowSuspendAfterHours: number;                      // when reservation.no_show triggers suspend
  readonly allowOfflineIssuanceKinds: KeyCredentialKind[];       // subset that may be minted offline
  readonly updatedAt:       ISODate;
}

4.1 Invariants​

  • M-1. MasterKey.keyCredentialId references a KeyCredential with holderKind === 'staff_master'.
  • M-2. A staff user has at most one active MasterKey per (propertyId, scope.kind) at a time; overlap on shift renewal is allowed only via explicit re-issue + revoke chain.
  • K-1. preferredOrder and fallbackChain are non-empty; every kind appears in at most one of them.
  • K-2. maxValidUntilExtensionHours defaults to 168 (1 week); cannot exceed 720 (30 days).

5. EncoderSession and OfflineIssuance​

export interface EncoderSession {
  readonly id:           EncoderSessionId;
  readonly tenantId:     TenantId;
  readonly propertyId:   PropertyId;
  readonly desktopDeviceId: Brand<string, 'DeviceId'>;
  readonly encoderModel: string;
  readonly transport:    'usb_hid' | 'serial';
  readonly openedAt:     ISODate;
  readonly closedAt?:    ISODate;
  readonly closeReason?: 'graceful' | 'usb_disconnect' | 'app_quit' | 'error';
}

export interface OfflineIssuance {
  readonly id:                 OfflineIssuanceId;
  readonly tenantId:           TenantId;
  readonly propertyId:         PropertyId;
  readonly desktopDeviceId:    Brand<string, 'DeviceId'>;
  readonly serial:             string;                       // included in cert payload
  readonly publicKeyEd25519:   string;                       // base64; private key on desktop only
  readonly allowedKinds:       KeyCredentialKind[];
  readonly maxValidWindowHours: number;                      // hard cap (default 48)
  readonly issuedAt:           ISODate;
  readonly expiresAt:          ISODate;                      // 90d from issuedAt
  readonly revokedAt?:         ISODate;
  readonly revokeReason?:      'rotation' | 'desktop_unbound' | 'tenant_request' | 'compromise';
}

5.1 Invariants​

  • E-1. EncoderSession.closedAt is set within 5s of USB disconnect or app quit; the local adapter persists the close reason.
  • O-1. OfflineIssuance.expiresAt - issuedAt === 90 days.
  • O-2. Revocation cascades — all credentials minted under a revoked cert are flagged for forced re-issue at next online check by the saga.
  • O-3. maxValidWindowHours <= 48 for all current tenants; future Phase 2 may negotiate longer for low-connectivity properties via ADR.

6. Per-vendor adapter signatures​

The LockPort interface (canonical declaration in docs/09 §4) is the only interface consumers depend on. Each per-vendor adapter implements LockPort plus an internal init contract:

export interface VendorAdapterModule<Cfg = unknown> {
  readonly vendor: VendorCode;
  load(cfg: Cfg, secretFetcher: SecretFetcher, telemetry: AdapterTelemetry): Promise<LockPort>;
  describeStatic(): { capabilities: LockCapabilities; latencyTargetsMs: { issueP95: number; revokeP95: number } };
}

// Per-vendor configuration shapes (no secret bytes — always Secret Manager pointers):

export interface TtLockAdapterConfig {
  apiBaseUrl:      string;            // 'https://euapi.ttlock.com'
  clientIdSecret:  string;            // Secret Manager resource name
  clientSecretSecret: string;
  appOwnerSecret:  string;            // tenant-onboarding-issued app owner ref
  defaultGatewayDeviceId?: string;    // optional cloud gateway for remote ops
  bleEnabled:      boolean;
  rateLimitPerMin: number;            // default 100
}

export interface SaltoAdapterConfig {
  cloudBaseUrl:    string;            // 'https://api.saltoks.com/xs4'
  apiKeySecret:    string;
  environment:     AdapterEnvironment;
  onPremConnector?: { url: string; mtlsCertSecret: string; mtlsKeySecret: string };
  svnPropagationToleranceSec: number; // default 120
}

export interface VostioAdapterConfig {
  cloudBaseUrl:    string;            // 'https://vostio.assaabloyhospitality.com/api'
  oauthTokenUrl:   string;
  clientIdSecret:  string;
  clientSecretSecret: string;
  environmentRef:  string;            // tenant-specific Vostio environment id
  rateLimitPerSec: number;            // default 30
}

export interface GenericWiegandAdapterConfig {
  // Cloud-side (CloudProxy) — relays to desktop:
  relayWsBaseUrl:  string;            // wss://lock-relay.melmastoon.ghasi.io
  desktopAckTimeoutMs: number;        // default 8000
}

export interface DesktopWiegandAdapterConfig {
  // Desktop-side (Electron main):
  encoderModel:    'hid_omnikey' | 'serial_acr122u' | 'serial_genericiso14443a' | string;
  transport:       'usb_hid' | 'serial';
  serialPath?:     string;            // for serial transport
  baudRate?:       number;
  pairingKeyKeychainRef: string;      // OS-keychain reference; never on disk plaintext
  mifareSectorConfig: { sector: number; keyAType: 'a' | 'b'; keyKeychainRef: string };
}

6.1 Vendor-specific extension hooks​

Adapters must implement only LockPort. They may expose internal extension hooks for vendor-specific capabilities the port does not model — but those are consumed by the saga only through capability flags via describeAdapter().capabilities. Examples:

Capability flagVendor with native supportSaga behavior when false
cardEncodingSalto, Wiegand, some TTLockSaga removes rfid_card from preferred kinds before dispatch
offlineIssuanceWiegand (always), TTLock BLE-direct (when paired), Salto (limited via SVN propagation)Cloud-only flow; no provisional path
scopeFloorsSalto, VostioSaga rejects floor-scoped masters; falls back to per-room enumeration
scopeAreasVostio, partial SaltoSame as above for areas

7. Domain events emitted by aggregates​

Each transition appends a typed DomainEvent to KeyCredentialAggregate.pendingEvents(). The application layer flushes them through the transactional outbox (04 §5). Event names map 1:1 to topic subjects in EVENT_SCHEMAS:

Aggregate transitionDomain eventTopic subject
request()KeyCredentialRequestedmelmastoon.lock.credential.requested.v1
markActive()KeyCredentialIssuedmelmastoon.lock.credential.issued.v1
markFailed()KeyCredentialFailedmelmastoon.lock.credential.failed.v1
update()KeyCredentialUpdatedmelmastoon.lock.credential.updated.v1
revoke()KeyCredentialRevokedmelmastoon.lock.credential.revoked.v1
suspend()KeyCredentialSuspendedmelmastoon.lock.credential.suspended.v1
unsuspend()KeyCredentialUnsuspendedmelmastoon.lock.credential.unsuspended.v1

LockDevice, MasterKey, EncoderSession, VendorAdapter all emit their own events; see EVENT_SCHEMAS for the full catalog.

8. Domain errors​

Defined under domain/errors/ and mapped to canonical codes by the presentation layer per ERROR_CODES — LOCK:

Error classCodeHTTP
VendorUnreachableErrorMELMASTOON.LOCK.VENDOR_UNREACHABLE502
KeyIssueFailedErrorMELMASTOON.LOCK.KEY_ISSUE_FAILED502
KeyRevokeFailedErrorMELMASTOON.LOCK.KEY_REVOKE_FAILED502
DeviceNotPairedErrorMELMASTOON.LOCK.DEVICE_NOT_PAIRED409
CredentialExpiredErrorMELMASTOON.LOCK.CREDENTIAL_EXPIRED410
CardEncoderOfflineErrorMELMASTOON.LOCK.CARD_ENCODER_OFFLINE503
CrossTenantReferenceErrorMELMASTOON.GENERAL.CROSS_TENANT_REFERENCE422
InvalidStateTransitionErrorMELMASTOON.GENERAL.VALIDATION_FAILED422 (sub-code invalid_state_transition)
WebhookSignatureInvalidErrorMELMASTOON.LOCK.WEBHOOK_SIGNATURE_INVALID (proposed addition)401
OfflineCertExpiredErrorMELMASTOON.LOCK.CREDENTIAL_EXPIRED (sub-code offline_cert_expired)410

Adapters translate vendor errors to one of the above; raw vendor error classes never escape the adapter boundary.

9. Builders (test utilities)​

Under domain/__builders__/, colocated with the aggregates. Used by unit + integration tests to construct valid aggregates with sensible defaults:

export const aKeyCredential = (over?: Partial<KeyCredential>): KeyCredential => ({
  id: 'key_01HX...' as KeyCredentialId,
  tenantId: 'tnt_01...' as TenantId,
  propertyId: 'ppt_01...' as PropertyId,
  holderKind: 'guest',
  reservationId: 'rsv_01...' as ReservationId,
  guestId: 'gst_01...' as GuestId,
  kind: 'mobile_app',
  rooms: ['rmu_01...'] as RoomId[],
  scope: {},
  validFrom: '2026-05-01T14:00:00Z',
  validUntil: '2026-05-03T11:00:00Z',
  state: 'active',
  vendor: 'ttlock',
  vendorAdapterId: 'vad_01...' as VendorAdapterId,
  vendorRef: '<opaque>',
  provisional: false,
  idempotencyKey: 'sha256...',
  version: 1,
  createdAt: '2026-04-30T10:00:00Z',
  updatedAt: '2026-04-30T10:00:01Z',
  ...over,
});

Builders are pure, deterministic by default, and accept overrides for specific test scenarios. They are never imported by production code (CI ESLint boundary check enforces).